Comentarios en Python — Una línea, multilínea y buenas prácticas

Los comentarios son líneas en tu código fuente que el intérprete de Python ignora por completo. Existen para los lectores humanos — para explicar la intención, documentar decisiones y señalar problemas — sin afectar cómo se ejecuta el programa. Este capítulo cubre todos los tipos de comentarios en Python, cuándo usar cada uno y las convenciones que mantienen legibles las bases de código grandes.

Comentarios de una línea

Un comentario de una línea comienza con el carácter almohadilla (#). Todo lo que va desde el # hasta el final de esa línea es ignorado por el intérprete.

# Calculate the area of a circle
radius = 5
area = 3.14159 * radius ** 2
print(area)  # outputs 78.53975

El comentario en la última línea — colocado después del código ejecutable en la misma línea — se llama comentario en línea. Úsalos con moderación; resérvalos para lógica genuinamente no obvia en lugar de repetir lo que el código ya dice.

Cuándo usar comentarios de una línea

• Explica el por qué se tomó una decisión, no el qué hace el código (el código muestra el qué).
• Marca soluciones temporales: # TODO: replace with database lookup.
• Deshabilita temporalmente una sola línea durante la depuración.

# FIXME: division by zero if user_count is 0
average = total_score / user_count

Comentarios multilínea

Python no tiene una sintaxis de comentarios multilínea dedicada como C tiene /* ... */. La forma idiomática de abarcar varias líneas es usar comentarios consecutivos de una sola línea, cada uno comenzando con #.

# This function converts a temperature in Celsius to Fahrenheit.
# The formula is: F = (C * 9/5) + 32
# Returns a float rounded to two decimal places.
def celsius_to_fahrenheit(c):
    return round((c * 9 / 5) + 32, 2)

print(celsius_to_fahrenheit(100))  # 212.0
print(celsius_to_fahrenheit(0))    # 32.0

La mayoría de los editores e IDEs de Python te permiten seleccionar múltiples líneas y alternar # en todas ellas a la vez (generalmente Ctrl+/ o Cmd+/).

Docstrings — comentarios de documentación estructurada

Python tiene una convención especial de literales de string llamada docstring (abreviatura de documentation string). Un docstring es un string de triple comillas colocado inmediatamente después de una cabecera def, class o de módulo. Aunque técnicamente es una expresión de string y no un comentario, sirve como mecanismo de documentación estándar y es accesible en tiempo de ejecución a través del atributo __doc__.

def greet(name):
    """Return a personalised greeting message.

    Args:
        name (str): The name of the person to greet.

    Returns:
        str: A greeting string.
    """
    return f"Hello, {name}!"

print(greet("Alice"))        # Hello, Alice!
print(greet.__doc__)         # prints the docstring above

Strings de triple comillas como comentarios de bloque

Dado que Python descarta los literales de string que no están asignados a nada, un string de triple comillas por sí solo (no en una posición def/class) a veces se usa como un comentario de bloque informal:

"""
This script processes the daily sales report.
It reads from sales.csv, aggregates by region,
and writes a summary to report.txt.
"""

import csv

Este patrón funciona, pero tiene un costo sutil: a diferencia de los comentarios con #, el intérprete sí analiza el string y puede conservarlo en el bytecode compilado. Para la documentación a nivel de módulo, prefiere un docstring de módulo adecuado (la primera instrucción en el archivo). Para otras explicaciones multilínea dentro de funciones, sigue usando líneas consecutivas con #.

Comentar código durante la depuración

Deshabilitar temporalmente código con comentarios es una técnica de depuración habitual:

def calculate_discount(price, rate):
    # discount = price * rate        # old flat-rate formula
    discount = price * rate if rate < 1 else price * (rate / 100)
    return price - discount

print(calculate_discount(100, 0.2))   # 80.0
print(calculate_discount(100, 20))    # 80.0

Una vez que hayas confirmado la corrección, elimina las líneas comentadas en lugar de dejarlas en la base de código de forma permanente — el código comentado obsoleto confunde a futuros lectores.

Directivas de comentarios especiales

Python y sus herramientas reconocen algunas líneas de comentarios que tienen significado legible por máquina:

La línea shebang

En sistemas tipo Unix, la primera línea de un script puede especificar el intérprete:

#!/usr/bin/env python3
# This line tells the OS to run the file with python3.

print("Hello from a standalone script!")

Esta línea es un comentario en lo que respecta a Python (comienza con #), pero el sistema operativo la usa cuando el archivo se ejecuta directamente (./script.py).

Declaración de codificación

Si tu archivo fuente usa una codificación de caracteres distinta de UTF-8 (el valor predeterminado desde Python 3), declárala en la primera o segunda línea:

# -*- coding: utf-8 -*-

Python 3 usa UTF-8 por defecto, por lo que esto rara vez se necesita hoy en día, pero puedes encontrarlo en código heredado.

Directivas para verificadores de tipos

Los verificadores de tipos como mypy respetan comentarios en línea especiales:

x = []  # type: ignore
result = some_function()  # type: ignore[return-value]

Estos suprimen errores de tipos específicos sin cambiar el comportamiento en tiempo de ejecución. Consulta el capítulo Variables de Python para más información sobre cómo Python maneja los tipos.

Buenas prácticas para comentarios

Seguir estas convenciones hará que tus comentarios sean genuinamente útiles:

PEP 8 — la guía de estilo oficial de Python — recomienda:

• Los comentarios en línea deben estar separados de la instrucción por al menos dos espacios.
• Cada comentario en línea debe comenzar con # (almohadilla, luego un espacio).
• Los comentarios de bloque que se aplican al código que sigue deben tener la misma sangría que ese código.

def apply_tax(price, tax_rate):
    # Tax rate is expressed as a decimal (e.g., 0.07 for 7 %).
    # Prices must be non-negative; validation happens upstream.
    tax = price * tax_rate
    return price + tax  # total including tax

Errores comunes que debes evitar

1. Dejar comentarios TODO sin rastrearlos

# TODO: handle the case where the file does not exist
data = open("data.txt").read()

Los TODO son útiles durante el desarrollo, pero deben estar vinculados a un sistema de seguimiento de incidencias, no dejarse indefinidamente en código de producción.

2. Comentar bloques grandes en lugar de eliminarlos

El control de versiones (git) preserva el historial. No es necesario mantener código comentado para la posteridad — elimínalo y usa git log si alguna vez necesitas recuperarlo.

3. Estilo inconsistente

La mezcla de #comment, # comment y ## comment en el mismo archivo hace que la base de código parezca desatendida. Acuerda un estilo y aplícalo de forma consistente.

Resumen

Los comentarios son una herramienta ligera que aportan valor cada vez que otro desarrollador (o tú mismo en el futuro) lee tu código. Para profundizar en temas relacionados, consulta Sintaxis de Python y Variables de Python.

Práctica