Comentarios

Los comentarios son fragmentos de texto que el intérprete de Python ignora al ejecutar el programa. Sirven para explicar el código a otras personas (o a nosotros mismos, en el futuro).

Comentarios de una línea

Se escriben precedidos del símbolo #. Todo lo que hay a partir de ese símbolo, hasta el final de la línea, es ignorado por el intérprete.

# Calcula el área de un círculo
radio = 5
area = 3.14159 * radio ** 2  # pi * r al cuadrado

Docstrings

Python también permite escribir cadenas de texto entre triple comilla ("""...""") como comentario de una o varias líneas. Cuando se colocan justo al principio de un módulo, una función o una clase, reciben el nombre de docstring y sirven como documentación oficial de ese elemento.

def area_circulo(radio):
    """Devuelve el área de un círculo a partir de su radio."""
    return 3.14159 * radio ** 2

Buenas prácticas

• Comenta el por qué de una decisión, no el qué hace el código (eso ya lo dice el propio código si está bien escrito).
• Evita comentarios obvios como x = x + 1 # suma 1 a x.
• Mantén los comentarios actualizados: un comentario desactualizado es peor que no tener comentario.