Python · Lección 07 de 27

Comentarios e indentación

El código se escribe una vez y se lee cientos de veces. Comentar bien e indentar correctamente es lo que convierte código funcional en código profesional y mantenible.

50–70 min Prerrequisitos: 06 Condicionales

Concepto teórico

¿Para qué comentar?

Un comentario es texto que Python ignora al ejecutar. Existe exclusivamente para que los humanos (incluido tu yo del futuro) entiendan el código. Parece trivial, pero en el mundo profesional la diferencia entre un proyecto mantenible y uno que nadie quiere tocar suele ser la calidad de los comentarios.

Hay una frase famosa en programación: "El código dice CÓMO, los comentarios dicen POR QUÉ." No comentes lo obvio (# sumo a + b antes de c = a + b). Comentá las decisiones no evidentes: por qué usaste una fórmula y no otra, por qué tratás un caso especial, qué regla de negocio implementa ese bloque.

Regla de oro: si necesitás un comentario para explicar QUÉ hace tu código, probablemente tu código sea demasiado complejo o tenga nombres poco claros. Los buenos nombres hacen que el código se explique solo. Los comentarios quedan para el POR QUÉ y el CONTEXTO.

Tipos de comentarios en Python

Comentario de una línea: empieza con #. Todo lo que viene después del # en esa línea es ignorado por Python.

# Esto es un comentario completo en una línea
saldo = 50000  # También podés comentar al final de una línea de código

Docstrings (documentación): son strings de triple comilla ("""...""" o '''...''') que documentan funciones, clases y módulos. A diferencia de los comentarios comunes, los docstrings se almacenan en memoria y se pueden acceder con help() o .__doc__. Son la forma oficial de documentar en Python.

def calcular_iva(precio, tasa=0.21):
    """
    Calcula el precio con IVA incluido.
    
    Args:
        precio (float): Precio sin IVA.
        tasa (float): Tasa de IVA. Default: 0.21 (21%).
    
    Returns:
        float: Precio con IVA incluido.
    """
    return precio * (1 + tasa)

Tip profesional: el estilo de docstrings más usado en la industria es el de Google (como el ejemplo de arriba). Otras opciones son NumPy style y Sphinx style. Lo importante es ser consistente en todo el proyecto.

¿Qué comentar y qué NO comentar?

✅ Comentá esto	❌ NO comentes esto
Decisiones de diseño no obvias	Código que se explica solo
Reglas de negocio: "BCRA exige ratio < 35%"	`# Sumo a más b` antes de `c = a + b`
Workarounds y sus razones	Cada línea individual
TODOs y FIXMEs para el futuro	Código comentado que "por las dudas" dejás
Fórmulas financieras con su fuente	Nombres de variables (si el nombre es bueno)
Límites y supuestos del algoritmo	Getters y setters triviales

Antipatrón: código comentado. Si tenés líneas de código comentadas "por las dudas", borralas. Para eso existe Git (control de versiones) — siempre podés recuperar código viejo. Código comentado acumula ruido, confunde, y nadie sabe si está ahí por algo o es basura.

Indentación: la estructura de Python

En la mayoría de lenguajes (Java, C++, JavaScript), los bloques de código se delimitan con llaves {}. En Python, los bloques se delimitan con indentación (espacios al inicio de la línea). Esto NO es una preferencia estética — es parte de la sintaxis del lenguaje. Si indentás mal, tu programa hace otra cosa o directamente da error.

La convención universal es usar 4 espacios por nivel de indentación. No 2, no 3, no tabs — 4 espacios. Esto está documentado en PEP 8 y es lo que usan el 99% de los proyectos Python del mundo.

if saldo > 0:
    # Nivel 1: 4 espacios
    print("Tenés saldo positivo")
    if saldo > 100000:
        # Nivel 2: 8 espacios
        print("Saldo alto")
        if saldo > 1000000:
            # Nivel 3: 12 espacios
            print("Sos millonario")
# Nivel 0: sin espacios — fuera de todos los bloques
print("Esto siempre se ejecuta")

IndentationError: el error más frustrante de principiante. Aparece cuando la indentación es inconsistente: mezclás tabs y espacios, o tenés 3 espacios donde deberían ser 4. VS Code con la extensión de Python resuelve esto automáticamente convirtiendo tabs a 4 espacios.

PEP 8: el estándar de estilo de Python

PEP 8 (Python Enhancement Proposal #8) es la guía oficial de estilo de Python. Seguirla no es obligatorio para que tu código funcione, pero sí es obligatorio en cualquier equipo profesional. Las reglas más importantes:

Indentación: 4 espacios por nivel
Largo de línea: máximo 79-120 caracteres
Espacios alrededor de operadores: x = 1, no x=1
Líneas en blanco: 2 entre funciones de nivel superior, 1 entre métodos dentro de una clase
Imports: uno por línea, al inicio del archivo, agrupados (stdlib → terceros → locales)
Trailing whitespace: no dejar espacios al final de las líneas

En el trabajo real: los equipos profesionales usan herramientas automáticas para forzar PEP 8: black (formateador automático), flake8 o pylint (verificadores de estilo), y los configuran en CI/CD para que el código que no cumple ni siquiera se pueda mergear. Aprender PEP 8 ahora te ahorra conflictos después.

Ejemplos explicados paso a paso

Ejemplo 1: Tipos de comentarios

Tres formas de comentar en Python: inline, de línea completa, y docstrings.

ejemplo_01_comentarios.pyPython

# Comentario de línea completa: describe el bloque que sigue
# Autor: Rodri Gonzalez
# Propósito: demostrar los tipos de comentarios en Python

saldo = 250000  # Comentario inline: explica esta línea específica

# Los comentarios se usan para:
# 1. Documentar decisiones de diseño
# 2. Explicar fórmulas complejas
# 3. Dejar notas (TODO, FIXME, HACK)

# TODO: reemplazar tasa hardcodeada por parámetro
TASA_PLAZO_FIJO = 0.065  # TEM del BCRA al 15/03/2025

# Docstring: documenta una función
def calcular_interes(capital, tasa=TASA_PLAZO_FIJO):
    """
    Calcula el interés simple de un período.
    
    Args:
        capital (float): Monto invertido.
        tasa (float): Tasa del período. Default: TEM BCRA.
    
    Returns:
        float: Interés generado.
    """
    return capital * tasa

interes = calcular_interes(saldo)
print(f"Interés: ${interes:,.0f}")

# Acceder al docstring
print(f"\nDocumentación: {calcular_interes.__doc__}")

Hacé clic en ▶ Ejecutar

Ejemplo 2: Buenos vs malos comentarios

Compará comentarios que ayudan con comentarios que molestan.

ejemplo_02_buenos_malos.pyPython

# ❌ MALOS COMENTARIOS (dicen lo obvio, son ruido)
x = 10  # Asigno 10 a x
y = 20  # Asigno 20 a y
z = x + y  # Sumo x e y
print(z)  # Imprimo z

print()

# ✅ BUENOS COMENTARIOS (explican el POR QUÉ, no el QUÉ)
# Ratio máximo regulado por BCRA Comunicación A-7876
MAX_RATIO_CUOTA_INGRESO = 0.35

ingreso_mensual = 350000
cuota_solicitada = 98000

# La regulación exige que la cuota no supere el 35% del ingreso
ratio = cuota_solicitada / ingreso_mensual
aprobado = ratio <= MAX_RATIO_CUOTA_INGRESO

# FIXME: considerar otros ingresos declarados (no solo el principal)
print(f"Ratio: {ratio:.1%} — {'Aprobado' if aprobado else 'Rechazado'}")

Hacé clic en ▶ Ejecutar

Ejemplo 3: La indentación como estructura

Moviendo una sola línea de lugar (cambiando su indentación) cambia completamente el comportamiento del programa.

ejemplo_03_indentacion.pyPython

saldo = 50000
limite = 100000

# VERSIÓN A: el "Reporte completo" está DENTRO del if
print("=== Versión A ===")
if saldo > 0:
    print(f"Saldo positivo: ${saldo:,}")
    if saldo > limite:
        print("Superaste el límite")
    else:
        print(f"Te faltan ${limite - saldo:,} para el límite")
    print("Reporte completo")  # ← dentro del if exterior

# VERSIÓN B: el "Reporte completo" está FUERA del if
print("\n=== Versión B ===")
if saldo > 0:
    print(f"Saldo positivo: ${saldo:,}")
    if saldo > limite:
        print("Superaste el límite")
    else:
        print(f"Te faltan ${limite - saldo:,} para el límite")
print("Reporte completo")  # ← fuera del if (sin indentación)

# La diferencia: en B, "Reporte completo" se imprime SIEMPRE.
# En A, solo si saldo > 0. Una indentación cambia la lógica.

Hacé clic en ▶ Ejecutar

Ejemplo 4: Desactivar código temporalmente con comentarios

Un uso legítimo de comentarios: desactivar líneas durante debugging. Pero no lo dejes así para siempre.

ejemplo_04_debug.pyPython

# Pipeline de datos simplificado
datos_crudos = ["$1,500", "$820", "$3,200", "N/A", "$950"]

datos_limpios = []
errores = 0

for d in datos_crudos:
    # Descomentá la siguiente línea para debugging:
    # print(f"DEBUG - Procesando: '{d}'")
    
    if d == "N/A" or d == "" or d is None:
        errores += 1
        # print(f"DEBUG - Saltando valor inválido: '{d}'")
        continue
    
    monto = float(d.replace("$", "").replace(",", ""))
    datos_limpios.append(monto)

print(f"Procesados: {len(datos_limpios)}")
print(f"Errores: {errores}")
print(f"Total: ${sum(datos_limpios):,.0f}")

# TIP: cuando termines de debuggear, BORRÁ los print de debug.
# No los dejes comentados "por las dudas".

Hacé clic en ▶ Ejecutar

Ejemplo 5: Código PEP 8 compliant vs no compliant

Las dos versiones funcionan igual, pero una es profesional y la otra no.

ejemplo_05_pep8.pyPython

# ❌ SIN PEP 8 (funciona pero es feo e inconsistente)
import math,random
x=math.sqrt(144)
y=random.randint(1,100)
def foo(a,b):return a+b
if x>10:print("si")
else :print("no")

print(f"Sin PEP 8: x={x}, y={y}, foo={foo(3,4)}")

# ✅ CON PEP 8 (profesional, legible, consistente)
import math
import random


def sumar(a, b):
    """Suma dos valores."""
    return a + b


raiz = math.sqrt(144)
aleatorio = random.randint(1, 100)

if raiz > 10:
    print(f"\nCon PEP 8: raíz = {raiz}")
else:
    print("Raíz <= 10")

resultado = sumar(3, 4)
print(f"Suma: {resultado}")
print(f"Aleatorio: {aleatorio}")

# La diferencia: el segundo se lee como texto natural.
# El primero hay que "descifrarlo".

Hacé clic en ▶ Ejecutar

Referencia rápida

Elemento	Sintaxis	Uso
Comentario inline	`codigo # comentario`	Notas breves sobre una línea
Comentario de línea	`# comentario`	Explicar el bloque que sigue
Docstring	`"""texto"""`	Documentar funciones/clases
TODO	`# TODO: tarea pendiente`	Marcar trabajo futuro
FIXME	`# FIXME: bug conocido`	Marcar problemas a resolver
HACK	`# HACK: workaround temporal`	Marcar soluciones temporales

Regla PEP 8	✅ Correcto	❌ Incorrecto
Indentación	4 espacios	Tabs, 2 espacios, mezcla
Espacios en operadores	`x = 1 + 2`	`x=1+2`
Imports	Uno por línea	`import os, sys, math`
Largo de línea	≤ 79-120 chars	Líneas de 200+ chars
Nombres	`snake_case`	`camelCase`, `x`
Líneas en blanco	2 entre funciones top-level	0 o 5 entre funciones

Ejercicios

Nivel 1 · Básico

Ejercicio 1: Agregar comentarios a código existente

Agregá un comentario a cada línea explicando qué hace (pero hacelo bien — explicá el POR QUÉ, no el QUÉ). El output debe incluir 6050.0.

ejercicio_01.pyDebe incluir "6050.0"

IVA = 0.21
precio = 5000
precio_final = precio * (1 + IVA)
print(precio_final)

Hacé clic en ▶ Ejecutar

Nivel 1 · Básico

Ejercicio 2: Escribir un docstring

Agregá un docstring a la función calcular_neto que explique qué hace, qué parámetros recibe y qué devuelve. Debe incluir 684500.

ejercicio_02.pyDebe incluir "684500"

def calcular_neto(bruto, tasa_deduccion=0.315):
    # Agregá un docstring acá
    return bruto * (1 - tasa_deduccion)

resultado = calcular_neto(1000000)
print(resultado)

Hacé clic en ▶ Ejecutar

Nivel 1 · Básico

Ejercicio 3: Arreglar indentación rota

Este código tiene la indentación mal. Arreglalo para que funcione. Debe incluir Saldo: positivo.

ejercicio_03.pyDebe incluir "Saldo: positivo"

saldo = 50000
if saldo > 0:
print("Saldo: positivo")
print(f"Monto: ${saldo:,}")
else:
print("Saldo: negativo")

Hacé clic en ▶ Ejecutar

Nivel 2 · Intermedio

Ejercicio 4: Código con bloques anidados correctos

Escribí un programa con 3 niveles de indentación: un if que verifica edad >= 18, dentro otro if que verifica ingreso >= 100000, y dentro un print. Debe incluir Aprobado nivel 3.

ejercicio_04.pyDebe incluir "Aprobado nivel 3"

edad = 25
ingreso = 150000
score = 720

# Armá 3 niveles de anidación:

Hacé clic en ▶ Ejecutar

Nivel 2 · Intermedio

Ejercicio 5: Función documentada con docstring

Creá una función calcular_iva(precio, tasa=0.21) con docstring completo (descripción, Args, Returns). Usala e imprimí el resultado. Debe incluir 12100.

ejercicio_05.pyDebe incluir "12100"

# Creá la función con docstring:

Hacé clic en ▶ Ejecutar

Nivel 2 · Intermedio

Ejercicio 6: Identificar y corregir errores de estilo PEP 8

Este código viola PEP 8 en al menos 5 formas. Corregilo. Debe incluir Resultado: 30.

ejercicio_06.pyDebe incluir "Resultado: 30"

import math,random
x=10;y=20
z=x+y
if z>0 :print(f"Resultado: {z}")
else:print("negativo")

Hacé clic en ▶ Ejecutar

Nivel 3 · Avanzado

Ejercicio 7: Script profesional completo

Escribí un script con: encabezado comentado (autor, fecha, descripción), constantes, una función con docstring, y uso formateado. Debe incluir Autor:.

ejercicio_07.pyDebe incluir "Autor:"

# Armá un script profesional completo:

Hacé clic en ▶ Ejecutar

Nivel 3 · Avanzado

Ejercicio 8: Pipeline comentado

Creá un mini pipeline que tome datos = ["$1,200", "N/A", "$800", "", "$2,500"], limpie los inválidos, convierta a números y sume. Comentá cada paso explicando POR QUÉ. Debe incluir 4500.

ejercicio_08.pyDebe incluir "4500"

datos = ["$1,200", "N/A", "$800", "", "$2,500"]

# Armá el pipeline comentando cada paso:

Hacé clic en ▶ Ejecutar

Nivel 3 · Avanzado

Ejercicio 9: Acceder a docstrings

Creá 2 funciones con docstrings distintos. Usá .__doc__ para imprimir la documentación de cada una. Debe incluir Documentación.

ejercicio_09.pyDebe incluir "Documentación"

# Creá 2 funciones con docstrings y mostrá su documentación:

Hacé clic en ▶ Ejecutar

Nivel 4 · Desafío

Ejercicio 10: Refactoring completo — de código ilegible a profesional

Reescribí este código para que sea 100% PEP 8 compliant: nombres descriptivos, comentarios útiles, indentación correcta, docstrings. El output numérico debe ser el mismo. Debe incluir Neto: 655500.

ejercicio_10_desafio.pyDebe incluir "Neto: 655500"

# Refactoreá este código ilegible:
a=950000;b=0.11;c=0.03;d=0.17
e=a*b;f=a*c;g=a*d
h=a-e-f-g
print(h)

# Reescribilo acá abajo con:
# - Nombres descriptivos
# - Constantes en MAYÚSCULAS
# - Comentarios que expliquen el POR QUÉ
# - Formato de moneda
# - Debe imprimir "Neto: 655500" (o similar con formato)

Hacé clic en ▶ Ejecutar

Resumen y conexión

Comentarios (#) explican el POR QUÉ, no el QUÉ. Docstrings ("""...""") documentan funciones.
La indentación (4 espacios) es obligatoria en Python — define la estructura del programa.
PEP 8 es la guía de estilo oficial: snake_case, espacios en operadores, imports separados, 79-120 chars por línea.
Código comentado (desactivado) debe borrarse — para eso existe Git.
Los buenos nombres hacen que el código se explique solo. Los comentarios son para el contexto y las decisiones.

En la siguiente lección (08 · Listas) vas a aprender la primera estructura de datos de Python: colecciones ordenadas y modificables que te permiten guardar muchos valores bajo un solo nombre.

Recursos: PEP 8 · PEP 257 — Docstring Conventions

Hecho con ❤️ por Rodri Gonzalez