Por qué importa saber comentar bien en Python
Todo programador acaba, tarde o temprano, escribiendo una línea que mañana no entenderá. Los comentarios existen para resolver ese problema, y también para otro uso más práctico: apagar temporalmente un fragmento de código mientras se prueba una hipótesis. Python, a diferencia de lenguajes como C, Java o JavaScript, no incluye una sintaxis específica para comentarios que abarquen varias líneas. Esa ausencia genera confusión, sobre todo entre quienes llegan desde otros lenguajes y buscan un equivalente a la pareja de símbolos de apertura y cierre.
En este tutorial recorreremos todo el panorama con la versión estable actual del lenguaje, Python 3.15, publicada en octubre de 2026. Todo lo que verás funciona igual desde las ramas 3.x anteriores, porque la sintaxis de comentarios no ha cambiado en años, pero conviene tener presente la versión para entender los matices de las anotaciones de tipo y de los docstrings que veremos más adelante.
Empezaremos por lo básico, el carácter almohadilla, y avanzaremos hacia los bloques, las cadenas de triple comilla y su verdadero papel, los docstrings, las anotaciones de tarea como TODO, los atajos de teclado de los editores más usados y las buenas prácticas que distinguen un comentario útil de un comentario que estorba. Si aún estás afianzando los fundamentos del lenguaje, te vendrá bien repasar esta guía completa para aprender Python pensando en tipos de datos, porque muchas decisiones sobre qué comentar dependen de entender qué información ya transmite el propio código.
Al terminar sabrás comentar una línea, un bloque entero o una función completa, sabrás por qué una cadena de triple comilla no es técnicamente un comentario, y tendrás un conjunto de reglas claras para decidir cuándo escribir un comentario y cuándo es mejor reescribir el código.
El comentario de una línea con almohadilla
La única forma real de comentario que existe en Python es la almohadilla, el símbolo #. Todo lo que aparece desde ese carácter hasta el final de la línea física es ignorado por el intérprete. No se tokeniza como código, no se ejecuta y no consume memoria en tiempo de ejecución, aunque sí permanece en el archivo fuente.
# Calcula el precio final con impuestos
precio_base = 80.0
iva = 0.21
precio_final = precio_base * (1 + iva)
print(precio_final)
Al ejecutar este programa, la primera línea no produce ningún efecto. El resultado en pantalla será simplemente el valor calculado.
96.8
Comentarios en línea al final de una sentencia
También puedes colocar el comentario a la derecha de una instrucción. En ese caso, la guía de estilo oficial recomienda separarlo del código con al menos dos espacios y dejar un espacio tras la almohadilla.
temperatura_max = 41 # grados Celsius, récord histórico local
limite_alerta = 38 # umbral definido por el equipo de operaciones
Este formato resulta cómodo para anotar unidades, orígenes de un dato o la razón de una constante. Sin embargo, abusar de él ensucia el código, sobre todo cuando las líneas se alargan y empiezan a superar el límite de ancho habitual de 79 o 88 caracteres.
La almohadilla dentro de una cadena no es un comentario
Un detalle que provoca errores de lectura es que el símbolo # dentro de una cadena de texto pertenece a la cadena. El analizador sintáctico sabe que está dentro de comillas y no lo trata como inicio de comentario.
etiqueta = "Pedido #4521"
print(etiqueta) # esto sí es un comentario real
Pedido #4521
Si en algún momento tu editor colorea mal un fragmento, revisa que las comillas estén bien cerradas. Una comilla olvidada hace que medio archivo parezca un comentario o, al revés, que un comentario parezca texto.
Comentarios y la línea shebang
Existe una excepción curiosa, la primera línea de un script ejecutable en sistemas Unix. La secuencia #! seguida de la ruta del intérprete es, para Python, un comentario más, pero para el sistema operativo es una instrucción de arranque.
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
print("Hola desde un script ejecutable")
La segunda línea, la declaración de codificación, ya no es necesaria en Python 3 porque UTF-8 es la codificación por defecto del código fuente. Se sigue viendo en proyectos antiguos y es inocua, pero en código nuevo puedes omitirla.
Comentar varias líneas seguidas
Cuando necesitas explicar algo con más de una frase, o desactivar un bloque completo, la solución canónica es repetir la almohadilla al inicio de cada línea. No hay otra sintaxis oficial para ello, y es lo que el propio proyecto Python usa en su biblioteca estándar.
# Esta función normaliza los nombres de usuario antes de guardarlos.
# Se eliminan espacios sobrantes, se pasa a minúsculas y se descartan
# los caracteres que el sistema de autenticación no admite.
def normalizar_usuario(nombre):
limpio = nombre.strip().lower()
return "".join(c for c in limpio if c.isalnum() or c in "._-")
La ventaja de este enfoque es su transparencia. Cualquier herramienta, desde un linter hasta un resaltador de sintaxis, entiende sin ambigüedad que esas líneas no son código. La desventaja es la incomodidad de editar a mano, algo que los atajos de teclado resuelven por completo y que veremos en una sección propia.
Desactivar código para depurar
Una técnica habitual consiste en comentar un fragmento para comprobar si es el responsable de un fallo. Imagina un cálculo de descuentos que no devuelve lo esperado.
def aplicar_descuento(total, cupon):
descuento = 0
# if cupon == "BLACK":
# descuento = total * 0.30
# elif cupon == "PRIMAVERA":
# descuento = total * 0.15
return total - descuento
print(aplicar_descuento(200, "BLACK"))
200
Al anular las ramas condicionales, el resultado deja de aplicar rebajas, y así se confirma que el fallo estaba en esa lógica o, al contrario, que el problema es otro. Es una herramienta de diagnóstico válida, pero con una condición importante: ese código comentado debe desaparecer antes de entregar el trabajo. Más adelante hablaremos de por qué dejarlo es una mala costumbre.
Un bloque comentado respeta la indentación
Al comentar líneas dentro de una función, alinea la almohadilla con el nivel de indentación del código que la rodea. Un comentario con sangría incorrecta no provoca error, porque el analizador ignora los comentarios al calcular la indentación, pero rompe la lectura visual.
def procesar(lote):
for item in lote:
# Se omiten los elementos sin identificador
if item.get("id") is None:
continue
guardar(item)
Mantener la alineación facilita que los demás identifiquen a qué bloque pertenece la nota.
Las cadenas de triple comilla no son comentarios
Es muy frecuente ver código donde un bloque de texto entre tres comillas dobles hace de comentario multilínea. Funciona en la práctica, y de ahí su popularidad, pero conviene entender qué ocurre realmente.
"""
Este texto parece un comentario,
pero en realidad es una cadena literal.
"""
print("El programa sigue funcionando")
El programa sigue funcionando
Una cadena de triple comilla es una expresión literal de tipo str. Si aparece suelta, sin asignarla a una variable ni usarla en una expresión, el intérprete la evalúa y la descarta. Por eso no tiene efecto visible. De hecho, el compilador de CPython elimina estas expresiones constantes sueltas durante la generación del código de bytes, de modo que tampoco cuestan tiempo de ejecución en la mayoría de los casos.
La excepción que lo cambia todo
La salvedad es la posición. Si la cadena es la primera sentencia de un módulo, una clase o una función, Python la guarda como documentación en el atributo __doc__. En ese caso ya no se descarta, sino que se conserva en memoria y puede consultarse en tiempo de ejecución.
def saludar(nombre):
"""Devuelve un saludo personalizado."""
return f"Hola, {nombre}"
print(saludar.__doc__)
Devuelve un saludo personalizado.
Aquí está la trampa. Quien usa triples comillas como comentario general dentro de una función y las coloca por casualidad como primera instrucción, está creando sin querer un docstring. Y si lo coloca a mitad del cuerpo, ya no es nada, solo una cadena huérfana.
Los problemas prácticos de usarlas como comentario
Hay varias razones por las que cadenas de triple comilla como comentarios no es una buena idea para desactivar código.
La primera es que no se pueden anidar. Si el bloque que quieres anular ya contiene una cadena de triple comilla, por ejemplo un docstring, el cierre del docstring interior termina prematuramente tu falso comentario y el resto del código queda expuesto como código válido o como un error de sintaxis.
"""
def calcular(x):
"""Dobla el valor recibido."""
return x * 2
"""
Este fragmento produce un error de sintaxis o un comportamiento inesperado, porque la segunda secuencia de tres comillas cierra la cadena exterior antes de tiempo. Usar comillas simples triples para el exterior ayuda, pero es un parche frágil.
La segunda razón es que las herramientas de análisis estático, los generadores de documentación y algunos linters tratan esas cadenas como expresiones sin efecto y pueden advertirte de ello. La tercera es de legibilidad, porque otros desarrolladores asumirán que la cadena suelta es un docstring mal colocado o un olvido.
Cuándo sí tiene sentido una cadena multilínea
Las triples comillas son idóneas para texto que realmente es un dato, como una consulta SQL larga, una plantilla de correo o un mensaje de ayuda. Ahí la cadena se asigna a una variable y se usa.
consulta = """
SELECT cliente_id, SUM(importe) AS total
FROM pedidos
WHERE fecha >= '2026-01-01'
GROUP BY cliente_id
"""
La regla práctica es sencilla. Si el texto se usa en el programa, es una cadena. Si es una explicación para humanos, es un comentario con almohadilla o un docstring.
Docstrings, la documentación que sí vive dentro del código
Un docstring es una cadena literal colocada como primera sentencia de un módulo, una clase, una función o un método. Python la asocia automáticamente al objeto y la expone mediante __doc__ y la función help(). Su finalidad es describir qué hace el objeto, no cómo lo hace, y a quién le sirve.
def convertir_a_kelvin(celsius):
"""Convierte una temperatura de grados Celsius a Kelvin.
Args:
celsius: temperatura en grados Celsius.
Returns:
La temperatura equivalente en Kelvin.
"""
return celsius + 273.15
El estándar de referencia es el PEP 257, que fija las convenciones generales. Establece, entre otras cosas, que la primera línea sea un resumen breve en modo imperativo y que, si hay más contenido, se separe con una línea en blanco.
Consultar la documentación en tiempo de ejecución
La ventaja sobre un comentario es que el docstring está disponible mientras el programa corre. Puedes consultarlo desde el intérprete interactivo con help().
help(convertir_a_kelvin)
Help on function convertir_a_kelvin in module __main__:
convertir_a_kelvin(celsius)
Convierte una temperatura de grados Celsius a Kelvin.
Args:
celsius: temperatura en grados Celsius.
Returns:
La temperatura equivalente en Kelvin.
Los editores modernos muestran este texto al pasar el ratón sobre el nombre de la función, y herramientas como Sphinx o MkDocs lo transforman en documentación navegable de forma automática.
Estilos habituales de docstring
Existen tres formatos extendidos. El estilo Google usa secciones como Args: y Returns:. El estilo NumPy usa subrayados con guiones bajo los títulos y es popular en el ámbito científico. El estilo reStructuredText, el de Sphinx, usa campos como :param nombre:. Lo importante es elegir uno y mantenerlo en todo el proyecto, porque mezclarlos confunde a las herramientas y a las personas.
class Inventario:
"""Gestiona las existencias de un almacén.
Attributes:
articulos: diccionario que asocia cada código con su cantidad.
"""
def __init__(self):
self.articulos = {}
def agregar(self, codigo, cantidad):
"""Suma unidades a un artículo existente o lo crea si no está."""
self.articulos[codigo] = self.articulos.get(codigo, 0) + cantidad
Docstring de módulo
El primer elemento de un archivo también puede ser un docstring, que describe el propósito del módulo completo. Debe aparecer antes de las importaciones, y solo puede precederlo la línea shebang o la declaración de codificación.
"""Utilidades para validar y formatear códigos de producto.
Este módulo agrupa las funciones que usan los servicios de catálogo
para comprobar longitudes, prefijos y dígitos de control.
"""
import re
Anotaciones de tipo frente a comentarios explicativos
Las anotaciones de tipo, o type hints, han reducido de forma notable la cantidad de comentarios necesarios. Antes era habitual escribir en un comentario qué tipo esperaba cada parámetro. Hoy esa información vive en la firma y puede verificarla una herramienta.
# Forma antigua: el tipo se explica en un comentario
def total_pedido(lineas):
# lineas: lista de tuplas (precio, cantidad)
return sum(p * c for p, c in lineas)
La versión moderna traslada el dato al propio código.
def total_pedido(lineas: list[tuple[float, int]]) -> float:
"""Suma el importe de todas las líneas de un pedido."""
return sum(precio * cantidad for precio, cantidad in lineas)
Desde Python 3.14, además, la evaluación de las anotaciones es diferida por defecto, lo que simplifica las referencias a clases definidas más abajo en el archivo y evita las comillas que antes se necesitaban en muchos casos. Es un buen ejemplo de cómo el lenguaje desplaza la documentación del comentario al código verificable.
Comentarios de tipo, un recurso casi obsoleto
Existía una sintaxis de comentario especial para indicar tipos en código compatible con versiones antiguas, por ejemplo # type: int. Hoy solo tiene sentido al mantener código que debe funcionar con intérpretes muy viejos. En proyectos nuevos, las anotaciones normales son la opción adecuada.
Directivas de herramientas dentro de comentarios
Algunos comentarios no son para humanos, sino para herramientas. Son directivas que los verificadores y formateadores interpretan.
import json # noqa: F401 (se importa por efectos secundarios)
valor: int = obtener() # type: ignore[assignment]
# fmt: off
matriz = [
1, 0, 0,
0, 1, 0,
0, 0, 1,
]
# fmt: on
Estos marcadores se deben usar con moderación y, siempre que se pueda, con un código de error específico para no silenciar más de lo necesario. Acompáñalos de una breve razón, porque dentro de seis meses nadie recordará por qué se ignoró esa advertencia.
Marcadores TODO, FIXME y similares
Una convención muy extendida es etiquetar los comentarios con palabras clave que los buscadores de tareas reconocen. Las más comunes son TODO para trabajo pendiente, FIXME para un error conocido, HACK para una solución provisional y NOTE para una aclaración relevante.
def exportar_informe(datos):
# TODO: añadir exportación a formato CSV además de JSON
# FIXME: falla cuando la lista de datos llega vacía
return json.dumps(datos)
Muchos editores resaltan estas etiquetas y las listan en un panel dedicado. Los linters pueden incluso fallar la integración continua si encuentran un FIXME sin resolver, según cómo se configure el proyecto.
Cómo escribir un TODO útil
Un TODO sin contexto es ruido. Para que sea accionable, indica quién lo asume o a qué incidencia se vincula, y por qué se pospone.
# TODO(marta): sustituir por el cliente asíncrono cuando se cierre la incidencia 482.
De este modo, el comentario se convierte en una referencia rastreable. Cuando la tarea se complete, se borra el comentario. Un repositorio con cientos de TODO antiguos acaba siendo una lista de deseos abandonada.
Buscar tareas pendientes desde la terminal
Puedes localizar todas las marcas con una búsqueda simple.
grep -rn "TODO\|FIXME" src/
src/informes.py:14: # TODO: añadir exportación a formato CSV además de JSON
src/informes.py:15: # FIXME: falla cuando la lista de datos llega vacía
src/auth/tokens.py:42: # TODO(marta): rotar la clave de firma cada trimestre
Integrar esta comprobación en un paso de revisión te da visibilidad sobre la deuda técnica sin necesidad de ninguna herramienta adicional.
Atajos de teclado para comentar en los editores
Escribir almohadillas a mano en veinte líneas es lento y propenso a errores. Todos los editores serios incluyen un atajo que comenta o descomenta la selección de golpe, y es la forma real de trabajar con bloques en Python.
Visual Studio Code
Selecciona las líneas y pulsa Ctrl más la barra inclinada en Windows y Linux, o Cmd más la barra inclinada en macOS. Para alternar el estado, el mismo atajo comenta si no estaba comentado y descomenta si ya lo estaba. Si prefieres un comentario de bloque, VS Code ofrece Mayús más Alt más A, pero en Python esa orden no tiene un delimitador propio y suele insertar cadenas de comillas, así que conviene evitarla y mantener el atajo de línea.
PyCharm
PyCharm usa Ctrl más la barra inclinada en Windows y Linux, y Cmd más la barra inclinada en macOS. Funciona igual con una línea o con una selección multilínea, y respeta la indentación de la selección al insertar la almohadilla.
Vim y Neovim
En Vim estándar no hay un atajo nativo, pero se logra con el modo de bloque visual. Pulsa Ctrl más V, selecciona las líneas con las flechas, luego Mayús más I, escribe la almohadilla y pulsa Esc. Para descomentar, selecciona la columna de almohadillas en modo bloque visual y pulsa x. En Neovim, desde la versión 0.10, existe el comentado integrado mediante gc sobre una selección o gcc para la línea actual.
Sublime Text y otros
Sublime Text emplea Ctrl más la barra inclinada para alternar comentarios de línea, igual que la mayoría de los editores gráficos. En editores de terminal como Nano, no hay atajo, y toca recurrir a macros o a otras herramientas.
Un truco con sed
Si necesitas comentar un rango de líneas desde la terminal sin abrir un editor, puedes usar sed.
sed -i '20,35s/^/# /' procesador.py
Este comando antepone la almohadilla seguida de un espacio a las líneas de la 20 a la 35. Para revertirlo, se invierte la sustitución, siempre con cuidado de no tocar comentarios que ya existieran. Hazlo bajo control de versiones para poder deshacer cualquier error con un simple descarte de cambios.
Qué comentar y qué no comentar
Saber la sintaxis es la parte fácil. El verdadero oficio está en decidir cuándo un comentario aporta valor. Una buena regla de partida es que el código dice cómo, y el comentario debe explicar por qué.
El comentario que repite el código
Este es el caso más común de comentario inútil. Describe lo que cualquiera lee directamente.
# Incrementa el contador en uno
contador += 1
# Recorre la lista de usuarios
for usuario in usuarios:
...
No añade información, y además se desactualiza con facilidad. Si cambias el incremento a dos, el comentario seguirá diciendo uno. Un comentario falso es peor que ninguno porque engaña al lector.
El comentario que explica una decisión
En cambio, estos son ejemplos de comentarios que merecen la pena porque recogen contexto que el código no puede expresar.
# Se reintenta tres veces porque la pasarela de pagos devuelve errores
# transitorios 502 durante las ventanas de mantenimiento nocturnas.
for intento in range(3):
respuesta = cobrar(pedido)
if respuesta.ok:
break
# Se usa un diccionario ordenado por inserción porque el informe
# debe respetar el orden en que se recibieron los eventos.
eventos_por_id = {}
Estos textos responden a una pregunta que el lector se haría inevitablemente, y su valor aumenta con el tiempo, no disminuye.
Cuando el comentario es síntoma de un nombre pobre
Muchos comentarios existen solo porque un nombre de variable o función no es claro. En vez de aclarar con una nota, es mejor renombrar.
# Antes
d = 7 # días de plazo para devolver un producto
# Después
DIAS_PLAZO_DEVOLUCION = 7
La segunda versión no necesita comentario. Es la mejor señal de que el código está bien escrito, porque el nombre carga con el significado.
Extraer una función en lugar de explicar un bloque
Cuando sientes la necesidad de poner un comentario encabezando un bloque largo, a veces lo que falta es una función con un nombre descriptivo.
# Antes
# Validar que el correo tenga formato correcto
if "@" not in correo or "." not in correo.split("@")[-1]:
raise ValueError("Correo inválido")
# Después
def validar_correo(correo: str) -> None:
if "@" not in correo or "." not in correo.split("@")[-1]:
raise ValueError("Correo inválido")
validar_correo(correo)
El nombre de la función hace el trabajo del comentario, y además el bloque se puede probar y reutilizar. Cuando un código se vuelve complejo, por ejemplo en algoritmos como los que se explican en el artículo sobre búsqueda binaria en Python 3.15 con bisect, variantes y trampas, los comentarios sobre los invariantes y los casos límite sí aportan mucho, porque ahí la intención es sutil y el código por sí solo no la transmite.
Errores frecuentes al comentar código
Incluso los desarrolladores con experiencia caen en algunas trampas recurrentes. Conocerlas ahorra tiempo de depuración y discusiones en las revisiones de código.
Dejar código comentado en el repositorio
Quizá el hábito más extendido. Se comenta un bloque por si hace falta después y se queda para siempre. Con el tiempo, nadie sabe si es seguro borrarlo ni si todavía funciona. La solución es confiar en el control de versiones. Si el código es necesario más adelante, estará en el historial de Git, y si no lo es, no debería ocupar espacio.
git log -S"aplicar_descuento_antiguo" --oneline
Este comando localiza los commits donde aparece o desaparece una cadena concreta, lo que permite recuperar código eliminado sin tenerlo comentado.
Olvidar actualizar los comentarios
Un cambio en la lógica sin la correspondiente actualización de la nota genera discrepancias. Para reducir este riesgo, mantén los comentarios cerca del código al que se refieren y revísalos en cada modificación, igual que revisas las pruebas.
Comentarios en lugar de excepciones o pruebas
A veces se usa un comentario para advertir de un comportamiento que debería controlarse con código.
# OJO: no pasar una lista vacía, rompe el cálculo
def promedio(valores):
return sum(valores) / len(valores)
Es más seguro convertir la advertencia en una comprobación.
def promedio(valores: list[float]) -> float:
if not valores:
raise ValueError("Se necesita al menos un valor")
return sum(valores) / len(valores)
El programa ahora protege su propio contrato, y la excepción comunica el requisito mejor que cualquier texto.
Una cadena mal sangrada que provoca un error inesperado
Un error clásico no es de comentarios sino de cadenas usadas como tales. Si utilizas una cadena de triple comilla en medio de un bloque, con una indentación distinta a la del código circundante, Python puede lanzar un error de indentación.
def calcular(x):
resultado = x * 2
"""
Este bloque está mal sangrado y confunde al analizador.
"""
return resultado
File "ejemplo.py", line 6
return resultado
IndentationError: unexpected indent
Con almohadillas este problema no existe, porque el analizador ignora por completo los comentarios al evaluar la sangría. Es otra razón para preferirlas.
Comentarios con información sensible
Contraseñas, claves de API o direcciones internas escritas en un comentario terminan en el repositorio y, potencialmente, en manos ajenas. Aunque borres la línea después, permanece en el historial. Usa variables de entorno o un gestor de secretos, y analiza el repositorio con una herramienta de detección de secretos antes de publicar.
Comentarios en un idioma mezclado
Mezclar español e inglés dentro del mismo proyecto dificulta la búsqueda y la lectura. Elige un idioma, ya sea el del equipo o el que exija la comunidad en proyectos abiertos, y úsalo de forma consistente tanto en comentarios como en docstrings. Los nombres de identificadores suelen ir en inglés por convención, pero los comentarios deben seguir la política del equipo.
Buenas prácticas de estilo según el PEP 8
La guía de estilo oficial dedica una sección entera a los comentarios, y sus recomendaciones son un buen punto de partida para cualquier equipo.
La primera es que los comentarios deben ser frases completas, con mayúscula inicial salvo que empiecen por un identificador. La segunda es que los comentarios de bloque se escriben con la almohadilla y un espacio, y se aplican al código que los sigue, con la misma indentación. La tercera es que los comentarios en línea se usen con moderación y separados al menos por dos espacios.
# Un comentario de bloque bien formado: describe el fragmento siguiente
# y mantiene la misma indentación que el código al que se refiere.
for pedido in pedidos_pendientes:
enviar(pedido)
total = calcular_total(pedidos) # comentario en línea, con dos espacios
Longitud de línea
Ajusta los comentarios al ancho de línea del proyecto. El PEP 8 sugiere 72 caracteres para comentarios y docstrings, y 79 para el código, aunque muchos equipos adoptan 88 o 100. Lo importante es que el formateador y el linter coincidan con la política elegida.
Mantener los comentarios cerca de la causa
Coloca la explicación justo antes de la línea que la motiva, no al inicio del archivo. Un comentario lejano pierde contexto y es más fácil que quede huérfano tras una refactorización.
Automatizar la comprobación
Herramientas como Ruff permiten verificar el estilo de docstrings y detectar comentarios problemáticos mediante reglas específicas. Una configuración sencilla en el archivo del proyecto activa esas comprobaciones.
[tool.ruff.lint]
select = ["E", "W", "D", "ERA"]
[tool.ruff.lint.pydocstyle]
convention = "google"
Las reglas D validan los docstrings según la convención elegida, y las ERA señalan código comentado que debería eliminarse. Con ello, parte de la disciplina se delega en la automatización y no depende de la memoria de nadie.
Ejemplo completo, de un script sin notas a uno bien documentado
Veamos todo junto con un caso práctico. Imagina un pequeño script que lee ventas y calcula el total por región. Primero, una versión descuidada.
def f(d):
r = {}
for x in d:
# r[x["r"]] = r.get(x["r"], 0) + x["v"]
"""
suma los valores
"""
k = x["r"]
r[k] = r.get(k, 0) + x["v"]
return r
Presenta todos los problemas que hemos visto. Nombres crípticos, código comentado, una cadena triple que actúa como falso comentario y ninguna documentación real. Ahora una versión cuidada.
"""Resumen de ventas por región."""
from collections import defaultdict
def totalizar_por_region(ventas: list[dict]) -> dict[str, float]:
"""Calcula el importe acumulado de ventas para cada región.
Args:
ventas: lista de registros con las claves "region" e "importe".
Returns:
Diccionario que asocia cada región con su total acumulado.
"""
totales: dict[str, float] = defaultdict(float)
for registro in ventas:
# defaultdict evita comprobar si la región ya existe
totales[registro["region"]] += registro["importe"]
return dict(totales)
if __name__ == "__main__":
muestra = [
{"region": "norte", "importe": 120.5},
{"region": "sur", "importe": 80.0},
{"region": "norte", "importe": 45.25},
]
print(totalizar_por_region(muestra))
{'norte': 165.75, 'sur': 80.0}
El único comentario real explica una decisión, el uso de defaultdict. El resto de la información la transmiten los nombres, las anotaciones de tipo y el docstring. Esa es la proporción ideal, pocos comentarios y todos con una razón de ser.
Probar los docstrings con doctest
Hay un uso de los docstrings que los convierte en algo todavía más valioso que una simple nota, la posibilidad de que contengan ejemplos ejecutables. El módulo estándar doctest busca en los docstrings fragmentos con el formato del intérprete interactivo y comprueba que el resultado coincide.
def es_par(numero: int) -> bool:
"""Indica si un entero es par.
>>> es_par(4)
True
>>> es_par(7)
False
"""
return numero % 2 == 0
Para ejecutar las comprobaciones, lanza el módulo con la opción de doctest.
python -m doctest -v paridad.py
Trying:
es_par(4)
Expecting:
True
ok
Trying:
es_par(7)
Expecting:
False
ok
1 items had no tests:
paridad
1 items passed all tests:
2 tests in paridad.es_par
2 tests in 2 items.
2 passed and 0 failed.
Test passed.
Gracias a esto, la documentación nunca se desfasa del comportamiento real sin que alguien se entere, porque la prueba fallaría. Es un excelente antídoto contra el problema de los comentarios obsoletos, al menos en las funciones públicas.
Comentarios en bucles y construcciones que merecen explicación
Hay estructuras donde un comentario breve suele ser apropiado. Los bucles con condiciones de salida sutiles son un buen ejemplo, ya que la intención no siempre se aprecia a simple vista. En patrones como los que se estudian en este recorrido por bucles while True en Python y sus patrones prácticos para 2026, una nota que aclare la condición de ruptura evita que el siguiente lector se pregunte si el bucle puede quedarse colgado.
while True:
linea = cola.obtener()
# La cola devuelve None cuando el productor termina; es la señal de parada
if linea is None:
break
procesar(linea)
Lo mismo ocurre con las expresiones regulares, las operaciones a nivel de bits y los cálculos con constantes mágicas, donde el significado no se deduce del código y una nota concisa ahorra minutos de análisis.
# Compara solo los 4 bits bajos: el protocolo reserva el resto para flags
codigo = mensaje & 0x0F
# Acepta fechas en formato AAAA-MM-DD, con mes 01-12 y día 01-31
patron = re.compile(r"^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$")
En ambos casos el comentario describe la intención, mientras que el código describe el mecanismo. Esa división de responsabilidades es la clave de todo el tutorial.
Comentarios y control de versiones en el trabajo diario
Un hábito que mejora el uso de los comentarios es apoyarse más en el historial de cambios. Los mensajes de commit son el lugar adecuado para contar la historia de un cambio, mientras que el comentario en el código debe describir cómo funciona ahora, no cómo se llegó hasta ahí.
Evita comentarios como el siguiente.
# Cambiado el 12 de marzo por Luis: antes usaba un bucle for
resultado = [x * 2 for x in datos]
Esa información pertenece al commit. Si alguien necesita saber quién modificó una línea y por qué, la herramienta correcta es la anotación de autoría.
git blame -L 10,14 src/transformar.py
a1b2c3d4 (Luis 2026-03-12 10:14:05 +0100 10) resultado = [x * 2 for x in datos]
Con esa salida llegas al commit exacto y a su mensaje. Los comentarios con fechas, autores o historiales de cambios envejecen mal y se acaban contradiciendo con lo que ocurre de verdad en el repositorio.
Comentarios en revisiones de código
Durante una revisión, un comentario nuevo suele ser una señal para preguntarse si el código puede simplificarse. No siempre, pero conviene mirar dos veces. Si el revisor necesita pedir una aclaración, tal vez el autor deba reescribir el fragmento o añadir la nota que falta. Esa conversación mejora el código más que cualquier regla estática.
Preguntas frecuentes sobre comentarios en Python
Existe una sintaxis oficial de comentario multilínea
No. El lenguaje solo reconoce la almohadilla. Cualquier otra técnica es una aproximación, ya sea repetir el símbolo en cada línea o usar cadenas literales que el intérprete descarta.
Las cadenas sueltas ralentizan el programa
En CPython, una cadena constante suelta que no sea el docstring se elimina al compilar, de modo que el coste en ejecución es nulo. Aun así, el consumo de memoria del archivo fuente y la claridad del código siguen siendo razones para no abusar de ellas.
Los comentarios afectan al rendimiento
Los comentarios con almohadilla no llegan al código de bytes. Solo afectan al tiempo de lectura del archivo durante la compilación, que es despreciable, y que además se omite cuando existe el archivo compilado en caché.
Puedo anidar comentarios
Con almohadillas, la pregunta no se plantea, porque un comentario termina al final de la línea y no hay delimitador de cierre. Si comentas una línea que ya contenía un comentario, simplemente tendrás dos almohadillas, y al descomentar, el comentario original sigue ahí.
# resultado = calcular(x) # este comentario original se conserva
Cómo comentar en archivos de configuración o cuadernos
En archivos de configuración como TOML o YAML también se usa la almohadilla. En cuadernos de Jupyter, el atajo del editor es el mismo que en VS Code o en el propio entorno web, y las celdas de texto con formato Markdown sirven para la documentación narrativa, mientras que las celdas de código conservan los comentarios con almohadilla.
Conclusiones
Comentar bien en Python se reduce a unas pocas ideas claras. La almohadilla es el único comentario real del lenguaje, y para un bloque se repite en cada línea, con la ayuda del atajo del editor para no hacerlo a mano. Las cadenas de triple comilla no son comentarios, sino literales que Python descarta salvo cuando ocupan la posición de un docstring, y su uso como sustituto de comentario multilínea trae problemas de anidamiento, de indentación y de confusión con la documentación.
Los docstrings son la herramienta adecuada para describir módulos, clases y funciones, y pueden incluso contener ejemplos comprobables con doctest. Las anotaciones de tipo trasladan al código información que antes vivía en notas, y los marcadores como TODO y FIXME ayudan a gestionar el trabajo pendiente siempre que lleven contexto y se limpien a tiempo.
Sobre todo, recuerda que un buen comentario explica el motivo, no repite el mecanismo. Antes de escribir una nota, pregúntate si un nombre mejor o una función extraída harían innecesaria la explicación. Elimina el código comentado y confía en Git, evita los secretos en los comentarios, mantén un único idioma y estilo, y automatiza las comprobaciones con un linter. Con estas prácticas, tu código en Python 3.15, y en las versiones que vengan, será más fácil de leer, de revisar y de mantener por ti y por quien lo herede.
