Los comentarios son para humanos
Python ignora los comentarios. Ese es todo el truco. Cualquier cosa que marques como comentario es invisible para el intérprete — está ahí exclusivamente para la persona que lea tu código, que normalmente es tu yo futuro, seis meses después, preguntándose qué pensaba tu yo pasado.
Dicho esto, un comentario que solo repite lo que el código hace obviamente no vale la pena escribirlo. Los mejores comentarios explican el por qué — una restricción, un workaround, una decisión que no es obvia desde el propio código. El código ya te dice qué está pasando.
Comentarios de una línea con #
La forma básica es un # seguido de tu nota:
También puedes añadir un comentario corto al final de una línea. Por convención, deja al menos dos espacios antes del #:
Python lee un # en cualquier sitio fuera de un string y trata el resto de la línea como comentario. Esa parte de "fuera de un string" importa: # dentro de comillas es solo un carácter.
El #section-2 dentro del string es parte de la URL. Python solo entra en modo "comentario" para el # que va después de que el string se cierre.
Comentar varias líneas
Python no tiene un comentario de bloque /* */. Para saltar varias líneas, pon # al principio de cada una:
Casi nunca escribes esos # a mano. Cualquier editor decente tiene un atajo de "toggle line comment" que añade o quita # en todas las líneas seleccionadas:
- VS Code: Cmd + / (macOS) o Ctrl + / (Windows/Linux)
- PyCharm: Cmd + / o Ctrl + /
- Vim: depende de tus plugins;
vim-commentaryenlazagccpara una línea ygcpara una selección.
Aprende el atajo en tu editor una vez, y "comentar este bloque para probar otra cosa" se convierte en una operación de una sola tecla.
El truco del string con triple comilla (y por qué no es un comentario real)
A veces verás código como este:
Técnicamente eso es una expresión string que se descarta. Python la parsea, la evalúa y tira el resultado. Se comporta como un comentario, pero no lo es. Estilísticamente, esto solo es buena idea en un sitio concreto: como docstring.
Docstrings: el único sitio donde pertenecen las triples comillas
Una docstring es un string con triple comilla colocado como la primera instrucción dentro de una función, clase o módulo. Python la reconoce como documentación y la hace disponible en tiempo de ejecución vía la función help() y el atributo __doc__:
Dos cosas hacen a las docstrings agradables:
- Herramientas como IDEs,
help()y generadores de documentación las leen automáticamente. Un comentario encima de la función no consigue nada de eso. - Describen la función en el sitio de la llamada — cuando alguien pasa el cursor sobre
discount(...)en su editor, la docstring aparece como tooltip.
Hay una convención (PEP 257) para lo que va en una docstring: un resumen de una línea en la primera línea, una línea en blanco, y luego una descripción más larga si hace falta. No te estreses con el formato exacto el primer día — una docstring simple de una línea es mucho mejor que no tener docstring.
Qué dicen los buenos comentarios
Unas cuantas guías que ahorran muchos disgustos más adelante:
- Prefiere describir por qué, no qué.
# Loop over the userses ruido;# Retry on 503 — Redis sometimes dies mid-deployes oro. - Actualiza los comentarios cuando cambies el código. Un comentario equivocado es peor que ningún comentario. Los comentarios desactualizados confunden activamente a los lectores.
- No comentes código y lo dejes ahí. Si no lo necesitas, bórralo. El control de versiones recuerda. Un archivo salpicado de bloques comentados se vuelve poco fiable rápido.
- Sáltate lo obvio.
x = x + 1 # increment xno añade nada.
Conclusión
Los comentarios son gratis de escribir y baratos de saltar. Recurre a ellos cuando estés dejando una nota que un lector agradecerá — una razón sutil por la que algo funciona, un enlace a un issue, un aviso sobre un caso borde. Usa docstrings cuando estés definiendo una función o clase. De lo contrario, deja que los nombres claros y las funciones pequeñas hablen.
Ahora tienes todo lo que necesitas para leer y escribir un archivo Python. El siguiente capítulo es donde el lenguaje empieza a hacer cosas de verdad: variables, tipos de datos y los valores que Python puede contener.
Preguntas frecuentes
¿Cómo escribo un comentario en Python?
Pon un # al principio de una línea (o en cualquier sitio de ella) y todo lo que venga después del # en esa línea es un comentario. Python ignora los comentarios por completo cuando ejecuta tu código.
¿Cómo comento varias líneas en Python?
Python no tiene sintaxis dedicada para comentarios multilínea. Pon # al principio de cada línea que quieras omitir. La mayoría de editores tienen un atajo de teclado que alterna # en todas las líneas seleccionadas a la vez — Cmd/Ctrl + / en VS Code, por ejemplo.
¿Los strings con triple comilla son comentarios en Python?
No exactamente. Un string con triple comilla que no se asigna a nada se comporta como un comentario en tiempo de ejecución, pero Python lo sigue parseando como un string. Ese patrón se usa sobre todo para docstrings — documentación para funciones, clases y módulos — no como comentario de propósito general.
