Comentarios en Python: buenas prácticas y ejemplos

Los comentarios en Python ayudan a explicar decisiones, restricciones y contexto que el código no puede expresar por sí solo. Un buen comentario facilita el mantenimiento; uno innecesario repite lo evidente, queda desactualizado y puede confundir más que ayudar.

En esta guía aprenderás comentarios de línea, comentarios inline, notas TODO, explicaciones de algoritmos, advertencias de seguridad y la diferencia entre comentarios y docstrings. También verás cómo escribir menos comentarios mediante nombres y funciones más claros. La sección oficial de PEP 8 sobre comentarios resume las convenciones principales.

Comentario de una línea

# Calcula el importe antes de aplicar impuestos.
subtotal = cantidad * precio

El símbolo # indica que el resto de la línea no se ejecuta. Deja un espacio después del símbolo para mejorar la lectura.

No repetir el código

# Mala práctica: suma uno a intentos
intentos += 1

El comentario no aporta información. Una explicación útil podría indicar el motivo:

# El proveedor permite tres reintentos antes de bloquear la cuenta.
MAX_INTENTOS = 3

El código ya explica qué ocurre; el comentario explica por qué existe esa regla.

Comentarios inline

TIEMPO_LIMITE = 30  # segundos permitidos por la API

Los comentarios al final de una línea deben ser breves y estar separados por espacios. Evítalos cuando hacen que la línea sea demasiado larga o cuando necesitan varias frases.

Explicar decisiones no obvias

# Se procesa en lotes de 100 porque la API rechaza páginas mayores.
for inicio in range(0, len(registros), 100):
    lote = registros[inicio:inicio + 100]
    enviar_lote(lote)

Este comentario conserva una restricción externa importante. Sin él, alguien podría “optimizar” el tamaño y romper la integración.

Explicar una solución temporal

# Solución temporal para archivos heredados en Latin-1.
# El nuevo proceso debe generar UTF-8 a partir de septiembre.
texto = ruta.read_text(encoding="latin-1")

Una solución temporal necesita contexto, responsable o condición de retirada. Evita comentarios vagos como “arreglar después”.

TODO, FIXME y notas de seguimiento

# TODO: añadir paginación cuando la API supere 1000 registros.
# FIXME: esta conversión pierde la zona horaria original.

Estas etiquetas son útiles cuando el equipo tiene una convención y una herramienta para revisarlas. Incluye información suficiente para comprender la tarea y, cuando sea posible, una referencia a un ticket.

Comentarios de bloque

# La puntuación combina tres factores:
# - exactitud: 60 %
# - velocidad: 25 %
# - consistencia: 15 %
# Los pesos fueron definidos por el equipo de evaluación.
puntuacion = (
    exactitud * 0.60
    + velocidad * 0.25
    + consistencia * 0.15
)

Un bloque debe preceder al código relacionado y mantenerse alineado con él. Si la explicación crece demasiado, considera moverla a la documentación del proyecto.

Comentarios y docstrings

Un comentario explica una decisión interna para quien mantiene el código. Un docstring describe cómo usar un módulo, clase, función o método.

def calcular_promedio(valores):
    """Devuelve el promedio de una secuencia no vacía."""
    # Se valida aquí para ofrecer un mensaje más claro que ZeroDivisionError.
    if not valores:
        raise ValueError("La secuencia no puede estar vacía")

    return sum(valores) / len(valores)

La guía de docstrings en Python explica parámetros, retornos, excepciones y herramientas. La convención formal está definida en la PEP 257.

Comentar código no es documentar una API

No conviertas cada función en una narración línea por línea. Para una interfaz pública documenta el contrato: qué recibe, qué devuelve, qué errores puede producir y qué efectos secundarios tiene. Los detalles internos pueden cambiar sin obligar a reescribir toda la documentación.

Nombres claros reducen comentarios

# Antes
x = p * q

# Mejor
subtotal = precio_unitario * cantidad

Un nombre descriptivo elimina la necesidad de explicar variables genéricas. La guía de PEP 8 en Python incluye convenciones para variables, funciones y clases.

Extraer una función

# Difícil de explicar dentro de un bloque enorme


def calcular_precio_final(precio, descuento, impuesto):
    precio_con_descuento = precio * (1 - descuento)
    return precio_con_descuento * (1 + impuesto)

Cuando necesitas varios comentarios para separar pasos, quizá el código deba dividirse en funciones. Consulta la guía de funciones en Python.

Comentarios de seguridad

# No registrar la respuesta completa: puede contener tokens y datos personales.
logging.info("Autenticación completada para usuario_id=%s", usuario_id)

Un comentario de seguridad debe advertir sobre una consecuencia real. Nunca incluyas contraseñas, tokens o claves privadas en comentarios; el repositorio conserva el historial aunque después borres la línea.

No usar comentarios como interruptores

# enviar_correo()
# guardar_reporte()
# publicar_resultado()

Bloques de código comentado dificultan saber qué versión es válida. El control de versiones ya conserva el historial. Elimina código muerto y utiliza configuración o parámetros para activar funciones.

Comentarios al depurar

Las impresiones temporales y fragmentos desactivados no deben quedar abandonados. Convierte información permanente en logging o pruebas. La guía de logging en Python muestra niveles y formatos adecuados.

Explicar una expresión regular

# Formato esperado: tres letras, guion y cuatro dígitos.
patron = r"^[A-Z]{3}-\d{4}$"

Los patrones compactos se benefician de una descripción del formato esperado y ejemplos válidos. Cuando una expresión es compleja, utiliza modo verbose y divide sus partes.

Comentarios en algoritmos

def busqueda_binaria(valores, objetivo):
    izquierda = 0
    derecha = len(valores) - 1

    while izquierda <= derecha:
        centro = (izquierda + derecha) // 2

        if valores[centro] == objetivo:
            return centro

        # Se descarta la mitad que no puede contener el objetivo.
        if valores[centro] < objetivo:
            izquierda = centro + 1
        else:
            derecha = centro - 1

    return -1

Comenta la idea o la invariancia, no cada asignación. El lector puede ver que una variable aumenta; necesita comprender por qué es correcto descartar una mitad.

Comentarios y excepciones

try:
    configuracion = cargar_configuracion()
except FileNotFoundError:
    # La ausencia del archivo es válida en la primera ejecución.
    configuracion = crear_configuracion_predeterminada()

Aquí el comentario explica por qué la excepción no representa un fallo. Para diseñar manejos claros, revisa try y except en Python.

Mantener comentarios actualizados

Durante una revisión de código, comprueba comentarios y docstrings igual que compruebas pruebas. Un comentario incorrecto puede ser más peligroso que ninguno, porque transmite confianza falsa.

Errores frecuentes

• Explicar sintaxis obvia.
• Dejar código antiguo comentado.
• Escribir TODO sin contexto.
• Usar comentarios para compensar nombres confusos.
• Documentar detalles internos como si fueran un contrato estable.
• Incluir datos sensibles o credenciales.
• Actualizar el código y olvidar la explicación.
• Escribir párrafos extensos cuando la información pertenece al README.

Lista de revisión

• ¿Explica una decisión o restricción no visible?
• ¿Sigue siendo correcto?
• ¿Podría reemplazarse por un nombre mejor?
• ¿Pertenece a un docstring o a documentación externa?
• ¿Revela información sensible?
• ¿Tiene una condición clara de eliminación si es temporal?

Conclusión

Los comentarios en Python son más valiosos cuando explican motivos, reglas externas, riesgos y decisiones de diseño. Evita repetir el código y elimina fragmentos muertos. Utiliza nombres claros, funciones pequeñas y docstrings para reducir la necesidad de explicaciones internas.

Un comentario debe ahorrar tiempo a quien investigue el código en el futuro. Si no añade contexto verificable o queda desactualizado con facilidad, es mejor mejorar la implementación o trasladar la información a una documentación más adecuada.