Comentarios y Documentación
Los comentarios son como notas que escribes para ti mismo (y otros programadores) para explicar qué hace tu código. Python los ignora completamente, pero son súper importantes para escribir código que sea fácil de entender.
¿Por qué son importantes los comentarios?
Imagínate que escribes un programa hoy y lo revisas en 6 meses. Sin comentarios, probablemente te preguntes: “¿Qué diablos estaba pensando cuando escribí esto?” 😅
Ejemplo sin comentarios:
x = 1000
y = x * 0.16
z = x + y
print(z)
El mismo ejemplo con comentarios:
# Calcular el precio final de un producto con IVA
precio_producto = 1000 # Precio base del producto
iva = precio_producto * 0.16 # IVA del 16%
precio_final = precio_producto + iva # Precio total
print(precio_final) # Mostrar el resultado
¿Cuál es más fácil de entender? ¡Exacto!
Tipos de comentarios en Python
1. Comentarios de una línea
Se escriben con # y Python ignora todo lo que viene después:
# Este es un comentario completo
print("Hola mundo") # Este es un comentario al final de la línea
# Puedes usar comentarios para "desactivar" código temporalmente
# print("Esta línea no se ejecutará")
print("Esta línea sí se ejecutará")
2. Comentarios de múltiples líneas
Python no tiene comentarios de múltiples líneas como otros lenguajes, pero puedes usar varias líneas con #:
# Este es un comentario
# que ocupa varias líneas
# para explicar algo complejo
print("Hola")
3. Docstrings (cadenas de documentación)
Para explicaciones largas, puedes usar comillas triples:
"""
Este es un docstring.
Se usa para documentar funciones, clases o módulos.
Puede ocupar varias líneas y es muy útil
para explicaciones detalladas.
"""
print("Mi programa")
Cuándo y cómo usar comentarios
✅ Buenos comentarios:
1. Explican el “por qué”, no el “qué”
# ✅ BUENO - explica por qué
precio_final = precio * 1.16 # Agregamos IVA del 16%
# ❌ MALO - solo repite lo que hace el código
precio_final = precio * 1.16 # Multiplicamos precio por 1.16
2. Explican lógica compleja
# ✅ BUENO
# Usamos el algoritmo de Luhn para validar números de tarjeta de crédito
# porque es el estándar de la industria bancaria
if validar_tarjeta(numero):
procesar_pago()
3. Advierten sobre cosas importantes
# ✅ BUENO
# CUIDADO: Esta función modifica la lista original
# Si necesitas conservar la original, haz una copia primero
def ordenar_lista(mi_lista):
mi_lista.sort()
4. Explican decisiones de diseño
# ✅ BUENO
# Usamos un diccionario en lugar de una lista
# porque necesitamos búsquedas rápidas por nombre
usuarios = {
"juan": {"edad": 25, "email": "juan@email.com"},
"maria": {"edad": 30, "email": "maria@email.com"}
}
❌ Malos comentarios:
1. Comentarios obvios
# ❌ MALO - es obvio lo que hace
edad = 25 # Asignar 25 a la variable edad
print(edad) # Imprimir la variable edad
2. Comentarios desactualizados
# ❌ MALO - el comentario no coincide con el código
# Calcular descuento del 10%
descuento = precio * 0.20 # ¡En realidad es 20%!
3. Comentarios que insultan
# ❌ MALO - no seas negativo
# Este código es horrible pero funciona
# TODO: Reescribir esta porquería
Comentarios para organizar tu código
Secciones del programa:
# ================================
# CONFIGURACIÓN INICIAL
# ================================
nombre_usuario = "Juan"
edad_usuario = 25
# ================================
# PROCESAMIENTO DE DATOS
# ================================
if edad_usuario >= 18:
print("Mayor de edad")
# ================================
# RESULTADOS FINALES
# ================================
print("Programa terminado")
Separadores visuales:
# --- Datos del usuario ---
nombre = "Juan"
edad = 25
# --- Validaciones ---
if edad >= 18:
print("Válido")
# --- Fin del programa ---
print("Terminado")
Comentarios TODO y FIXME
Estos son comentarios especiales que muchos editores resaltan:
# TODO: Agregar validación de email
email = input("Tu email: ")
# FIXME: Este cálculo no funciona con números negativos
resultado = calcular_raiz(numero)
# HACK: Solución temporal hasta arreglar el bug #123
if sistema == "windows":
ruta = ruta.replace("/", "\\")
# NOTE: Esta función será removida en la versión 2.0
def funcion_antigua():
pass
Documentando tu primer programa
Vamos a tomar un programa simple y documentarlo correctamente:
Antes (sin documentación):
n = input("Nombre: ")
e = int(input("Edad: "))
if e >= 18:
print("Hola", n, "eres mayor")
else:
print("Hola", n, "eres menor")
Después (bien documentado):
"""
Programa: Verificador de Mayoría de Edad
Autor: [Tu nombre]
Fecha: [Fecha actual]
Descripción: Solicita nombre y edad al usuario y determina
si es mayor o menor de edad.
"""
# ================================
# ENTRADA DE DATOS
# ================================
# Solicitar información personal al usuario
nombre_usuario = input("Ingresa tu nombre: ")
edad_usuario = int(input("Ingresa tu edad: "))
# ================================
# PROCESAMIENTO
# ================================
# Verificar mayoría de edad (18 años en México)
if edad_usuario >= 18:
print("Hola", nombre_usuario, "eres mayor de edad")
else:
print("Hola", nombre_usuario, "eres menor de edad")
# ================================
# FIN DEL PROGRAMA
# ================================
# El programa termina aquí
Comentarios en diferentes idiomas
Aunque tu código esté en español, los comentarios técnicos a veces se escriben en inglés:
# Configuración del sistema
API_KEY = "mi_clave_secreta"
# TODO: Add error handling for API failures
# FIXME: Memory leak in data processing function
def procesar_datos():
pass
Esto es normal y está bien. Lo importante es ser consistente.
Herramientas para comentarios
En VS Code:
- Ctrl + / - Comentar/descomentar líneas seleccionadas
- Shift + Alt + A - Comentario de bloque
- Las extensiones pueden resaltar TODO, FIXME, etc.
En Thonny:
- Ctrl + / - Comentar/descomentar
- Ctrl + Shift + / - Comentario de bloque
Ejercicios prácticos
Ejercicio 1: Documenta este código
p = float(input("Precio: "))
d = float(input("Descuento %: "))
df = p * (d / 100)
pf = p - df
print("Precio final:", pf)
Ejercicio 2: Crea un programa documentado
Escribe un programa que:
- Tenga un docstring al inicio
- Pida dos números al usuario
- Calcule y muestre la suma, resta, multiplicación y división
- Use comentarios para explicar cada sección
- Use nombres de variables descriptivos
Ejercicio 3: Encuentra los problemas
¿Qué está mal con estos comentarios?
# Este programa suma dos números
a = 5 # Variable a es igual a 5
b = 10 # Variable b es igual a 10
resultado = a * b # Sumamos a y b
print(resultado) # Imprimimos el resultado
Buenas prácticas para comentarios
1. Escribe comentarios mientras programas
No los dejes para después - es fácil olvidar qué estabas pensando.
2. Mantén los comentarios actualizados
Si cambias el código, actualiza los comentarios.
3. Usa un estilo consistente
Decide un formato y úsalo en todo tu programa.
4. No comentes código obvio
Si el código es claro, no necesita comentarios.
5. Explica el contexto
¿Por qué tomaste esa decisión? ¿Qué problema resuelve?
Plantilla para tus programas
Aquí tienes una plantilla que puedes usar para tus programas:
"""
Programa: [Nombre del programa]
Autor: [Tu nombre]
Fecha: [Fecha]
Versión: 1.0
Descripción:
[Explica qué hace tu programa]
Uso:
[Cómo se usa el programa]
"""
# ================================
# IMPORTACIONES Y CONFIGURACIÓN
# ================================
# [Aquí van los imports si los hay]
# ================================
# FUNCIONES
# ================================
# [Aquí van las funciones si las hay]
# ================================
# PROGRAMA PRINCIPAL
# ================================
if __name__ == "__main__":
# [Aquí va tu código principal]
pass
Resumen
Los comentarios son esenciales para:
- ✅ Explicar código complejo
- ✅ Documentar decisiones de diseño
- ✅ Ayudar a otros programadores (¡y a ti mismo en el futuro!)
- ✅ Organizar secciones de código
- ✅ Marcar tareas pendientes (TODO)
Recuerda: el código se escribe una vez, pero se lee muchas veces. ¡Haz que sea fácil de entender!
💡 Consejo profesional: Un buen programador no es el que escribe código complejo, sino el que escribe código simple y bien documentado que cualquiera puede entender. ¡Los comentarios son tu mejor herramienta para esto!