Python / Sintaxis / Comentarios

En Python, un comentario empieza con # fuera de una cadena y termina al final de la línea. Para comentar varias líneas, añada # a cada una. Las comillas triples crean una cadena, que puede utilizarse como docstring, y no son una sintaxis de comentario.

Comentarios de línea y # dentro de cadenas

Los comentarios ordinarios explican las intenciones y condiciones del código; su contenido se ignora durante el análisis sintáctico. Pueden ocupar toda una línea o aparecer después de una instrucción. Las reglas oficiales de comentarios de Python describen su alcance.

Solo necesita Python 3. Guarde cada ejemplo completo como comments_example.py en UTF-8 y ejecute python comments_example.py, o python3 según su instalación. Sustituya el contenido del archivo para probar los otros ejemplos de forma independiente.

# Calculate the total before discounts.
price = 100
quantity = 2  # Number of items
print(price * quantity)

Resultado esperado:

200

Dentro de las comillas, # forma parte del texto. Por tanto, no recorta una frase ni el fragmento de una URL:

print("# This is part of a string")
print("https://example.com/page#section")

# This is part of a string
https://example.com/page#section

Marcar cada línea de una explicación larga

Python no tiene una sintaxis separada de comentario de bloque como /* ... */ en C. Comente cada línea y mantenga su sangría alineada con el código descrito para mostrar la relación.

# The sample uses a fixed discount rate.
# Production rules may depend on the customer.
base_price = 100
discount_rate = 0.1
print(base_price * (1 - discount_rate))

90.0

Para desactivar código temporalmente, comente sus líneas; para recuperarlo, elimine las marcas. Los editores suelen automatizarlo mediante un comando para comentar varias líneas. Conserve las implementaciones antiguas en el historial de versiones en lugar de acumular alternativas comentadas en el archivo.

Las comillas triples y las docstrings son cadenas

Tres comillas simples o dobles delimitan un literal de cadena que puede ocupar varias líneas. Cuando es la primera instrucción de un módulo, clase o función, se convierte en una docstring, disponible mediante __doc__ y las herramientas de ayuda. Consulte la explicación oficial de las docstrings.

def greet(name):
    """Return a greeting for name."""
    return f"Hello, {name}"

print(greet("Ada"))
print(greet.__doc__)

Hello, Ada
Return a greeting for name.

Este valor documenta la función y se puede consultar, a diferencia de un comentario explicativo ordinario. La misma notación también almacena datos reales:

notes = """first line
second line"""
print(notes.splitlines())

['first line', 'second line']

Encerrar código arbitrario entre comillas triples no lo convierte en un verdadero comentario. Si contiene las mismas comillas puede romper la sintaxis, y su posición puede hacer que se interprete como docstring. Utilice # para desactivar líneas.

Un bloque solo con comentarios necesita una instrucción

Los bloques de def, if y otras construcciones necesitan una instrucción real. Los comentarios no cuentan, por lo que dejar únicamente comentarios puede producir IndentationError. La instrucción pass, que no hace nada, sirve como marcador provisional.

source = "def todo():\n    # Implement later\n"
try:
    compile(source, "example", "exec")
except IndentationError:
    print("IndentationError")

def todo():
    # Implement later
    pass

print(todo())

IndentationError
None

La primera parte compila código incorrecto guardado en una cadena y captura el error para que el ejemplo continúe. La función posterior es válida gracias a pass. Sin un retorno explícito, su llamada devuelve None.

Explicaciones útiles y directivas especiales

PEP significa Python Enhancement Proposal. Las recomendaciones de PEP 8 sobre comentarios advierten de los comentarios que contradicen el código. Explique decisiones, restricciones externas y condiciones importantes en vez de repetir acciones obvias, y actualice los comentarios al modificar el código. Un comentario al final de una línea suele llevar al menos dos espacios antes de # y uno después.

Algunos comentarios tienen significado para herramientas o para la lectura del archivo. Una declaración de codificación válida en la primera o segunda línea puede afectar a su interpretación; Python 3 usa UTF-8 por defecto. Distinga las directivas de linters y verificadores de tipos de las explicaciones y revise las advertencias antes de ocultarlas indiscriminadamente.