Comentarios

0.1 Motivación

El código se escribe una vez, pero se lee muchas veces. Los comentarios son la forma en que te comunicas con otros programadores (y contigo mismo en el futuro). Un buen comentario explica el “por qué” detrás del “qué”, haciendo que tu código sea más fácil de entender, mantener y depurar. Además, los comentarios son una herramienta poderosa para probar código temporalmente sin eliminarlo.

0.2 Intuición

Imagina que estás escribiendo un libro de cocina. Las instrucciones (el código) son los pasos de la receta. Los comentarios son como notas al margen: “este paso es importante porque evita que se queme”, “aquí puedes sustituir el ingrediente si no lo tienes”. El chef (Python) ignora completamente tus notas al margen y solo sigue las instrucciones principales.

0.3 Modelo mental

Los comentarios en Python:

1. Comienzan con #: todo lo que sigue en esa línea es ignorado por Python.
2. Pueden estar al inicio de la línea o al final de una línea de código.
3. No tienen efecto en la ejecución: son solo para humanos.
4. No existe sintaxis oficial para comentarios de múltiples líneas, pero hay formas de simularlos.

0.4 Desarrollo

# Esto es un comentario
print("Hola mundo")  # Esto también es un comentario

precio = 100      # Precio base sin impuestos
iva = 0.21        # IVA del 21%
total = precio * (1 + iva)  # Cálculo del precio final

# print("Esta línea no se ejecuta")
print("Esta línea sí se ejecuta")
# Salida: Esta línea sí se ejecuta

# Esto es un comentario
# que ocupa varias líneas
# y explica algo complejo
print("Hola")

"""
Este es un comentario
que ocupa varias líneas
Python lo ignora porque no está asignado a una variable
"""
print("Hola")

def calcular_area(base, altura):
    """
    Calcula el área de un rectángulo.

    Args:
        base (float): La base del rectángulo
        altura (float): La altura del rectángulo

    Returns:
        float: El área calculada
    """
    return base * altura

0.5 Ejemplos

Mínimo — Comentarios simples:

# Saludo inicial
print("Hola")  # Muestra un saludo

Progresivo — Comentarios para explicar lógica:

# Cálculo de descuento
precio_original = 120
descuento = 0.15  # 15% de descuento

# El precio final es el original menos el descuento
precio_final = precio_original - (precio_original * descuento)
print(precio_final)  # Muestra: 102.0

Real — Documentación en un script de configuración:

# ==========================================
# CONFIGURACIÓN DEL SISTEMA
# ==========================================

# Configuración de la base de datos
# Usamos SQLite para desarrollo local
DB_HOST = "localhost"
DB_PORT = 5432

# Límites del sistema
MAX_USERS = 100  # Máximo de usuarios simultáneos
TIMEOUT = 30     # Tiempo de espera en segundos

# DEBUG = True   # Descomentar para modo depuración
DEBUG = False    # Modo producción

0.6 Errores comunes

0.7 Buenas prácticas

• Comenta el “por qué”, no el “qué”: el código ya dice qué hace.

  python

  # ❌ Poco útil
  x = x + 1  # Incrementa x en 1
  
  # ✅ Útil
  x = x + 1  # Contador de intentos fallidos

• Mantén los comentarios actualizados: un comentario desactualizado es peor que ninguno.

• Usa comentarios de bloque para secciones largas:

  python

  # ==========================================
  # SECCIÓN: VALIDACIÓN DE DATOS
  # ==========================================

• Documenta funciones con docstrings (triple comilla):

  python

  def saludar(nombre):
      """Saluda al usuario por su nombre."""
      print(f"Hola, {nombre}")

• No abuses de los comentarios: el código limpio y autoexplicativo es mejor que el código lleno de comentarios.

0.8 Ejercicio

Básico — Agrega comentarios apropiados

El siguiente código funciona pero no tiene comentarios. Agrega comentarios que:

1. Expliquen qué hace cada sección
2. Documenten qué hace la función
3. Desactiven temporalmente una línea de código (sin eliminarla)

def calcular_total(precio, cantidad):
    return precio * cantidad

precio_producto = 25.50
unidades = 4
total = calcular_total(precio_producto, unidades)
print(total)
print("Fin del cálculo")

Solución (no mires hasta haberlo intentado):

# Función que calcula el total de una compra
def calcular_total(precio, cantidad):
    """Multiplica el precio por la cantidad para obtener el total."""
    return precio * cantidad

# Datos del producto
precio_producto = 25.50  # Precio unitario en euros
unidades = 4             # Cantidad de unidades compradas

# Cálculo del total
total = calcular_total(precio_producto, unidades)

# Mostrar resultados
print(total)            # Muestra el total
# print("Fin del cálculo")  # Desactivado temporalmente

0.9 Síntesis

• # inicia un comentario de una línea.
• Todo después de # es ignorado por Python.
• Comentarios al final de línea explican código específico.
• Múltiples # para comentarios de varias líneas (o triple comilla).
• Desactivar código comentando líneas es útil para pruebas.
• Docstrings (""") documentan funciones y clases.
• Buen comentario: explica el “por qué”, no repite el “qué”.

0.10 Qué sigue

• Relacionado: variables (cómo nombrar bien las variables para reducir necesidad de comentarios)
• Siguiente tema: Variables — aprenderás a almacenar datos con nombres claros y autoexplicativos.