Comentarios y Documentación

Los comentarios son anotaciones en el código fuente que Python ignora por completo al ejecutar el programa. No hacen nada en tiempo de ejecución. Su trabajo es hablarles a los desarrolladores, incluyéndote a ti mismo cuando vuelvas a este código tres meses después y no recuerdes por qué hiciste lo que hiciste.

¿Por qué son importantes los comentarios?

El código te dice cómo se hace algo. Los comentarios te dicen por qué. Esta distinción no es sutil: es la diferencia entre código que puedes mantener y código que tienes que reescribir desde cero.

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

El segundo ejemplo es legible. El primero es un acertijo.

Tipos de comentarios en Python

1. Comentarios de una línea

Se escriben con el símbolo #. Python descarta todo lo que sigue en esa línea, sin excepciones.

# 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 una sintaxis dedicada para bloques de comentarios. Lo que sí permite es encadenar líneas con # cuando necesitas explicar algo que no cabe en una sola.

# Este es un comentario
# que ocupa varias líneas
# para explicar algo complejo

3. Docstrings (cadenas de documentación)

Para documentar funciones, clases o módulos enteros se usan comillas triples (""" o '''). A diferencia de los comentarios con #, los docstrings quedan accesibles en tiempo de ejecución a través del atributo __doc__ del objeto.

"""
Este es un docstring.
Se usa para documentar el propósito de un módulo o función.
Es accesible a través del atributo __doc__ del objeto.
"""

print("Mi programa")

Buenas prácticas

Buenos comentarios:

1. Explican el “por qué”

# Bien: explica el razonamiento
precio_final = precio * 1.16  # Agregamos IVA del 16%

# Mal: solo repite el código
precio_final = precio * 1.16  # Multiplicamos precio por 1.16

2. Aclaran lógica compleja

# El descuento es del 15% porque la promoción "VERANO"
# sigue activa hasta el 31 de agosto
descuento = 0.15

3. Etiquetas estándar

• TODO: Tarea pendiente.
• FIXME: Código que necesita corrección.
• NOTE: Nota importante.

# TODO: Agregar la dirección de envío a la ficha
nombre_cliente = "Ana Torres"

# FIXME: El precio está escrito a mano; debería salir del catálogo
precio = 19.99

Documentando tu primer programa

Un programa bien documentado hace explícito lo que de otro modo hay que inferir: para qué sirve, quién lo escribió, cuándo. Es una cortesía hacia quien lea el código después.

Plantilla recomendada:

"""
Programa: Ficha de Empleado del Almacén
Autor: [Tu nombre]
Fecha: [Fecha actual]
Descripción: Registra los datos de un empleado nuevo
            y los publica en el tablero de avisos.
"""

# ================================
# DATOS DEL EMPLEADO
# ================================
nombre = "Carlos"
puesto = "Operador de Montacargas"
turno = "Nocturno"  # El almacén opera 24 horas

# ================================
# PUBLICACIÓN EN EL TABLERO
# ================================
print("--- NUEVO INGRESO ---")
print(nombre)
print(puesto)
print(turno)

Recuerda: el código se escribe una vez, pero se lee muchas veces. Haz que sea fácil de entender.