Buenas prácticas y PEP 8

El código se escribe una vez y se lee cientos. PEP 8 es la guía de estilo de Python — y detrás de cada regla hay una razón de legibilidad. Este es el resumen profesional.

Nombres: cada cosa con su formato

# snake_case: funciones y variables
def calcular_promedio(): ...
total_productos = 10

# PascalCase: clases
class UsuarioPremium: ...

# MAYUSCULAS: constantes (que no deberían cambiar)
TASA_IVA = 0.19
MAXIMO_INTENTOS = 3

# _prefijo: uso interno, "no toques esto desde afuera"
_cache_interno = {}

El Zen de Python

Ejecuta import this en cualquier intérprete. Los aforismos que más importan:

• Readability counts — la legibilidad cuenta
• Explicit is better than implicit — explícito mejor que implícito
• Simple is better than complex — simple mejor que complejo
• There should be one obvious way to do it — debe haber una forma obvia

No son poemas: son criterios de decisión. Ante dos soluciones, gana la más legible.

Docstrings: documentación viva

Un docstring va en la primera línea del módulo, clase o función, entre triple comilla:

def calcular_cuota(capital, tasa_anual, meses):
    """Calcula la cuota mensual de un préstamo de pago fijo."""
    ...

• Una línea si basta: qué hace (no cómo)
• Para APIs públicas, el formato de parámetros y retorno
• Se accede con help(funcion) y funcion.__doc__ — vive con el código, a diferencia del wiki

La diferencia con un comentario #: el docstring documenta el contrato (qué promete); los comentarios explican el porqué de decisiones no obvias.

Formato que PEP 8 exige

# Espacios alrededor de operadores, después de comas
total = precio * cantidad
coordenadas = (10, 20, 30)

# Líneas de máximo 79-99 caracteres (elige y sé consistente)

# Dos líneas en blanco antes de una definición de nivel superior


def nivel_superior(): ...

# Comparaciones con None: usar is
if resultado is None:      # nunca == None
    ...

# No compares con True/False explícitamente
if esta_activo:            # no: if esta_activo == True:
    ...

Y deja que las herramientas hagan el trabajo sucio: ruff (linter + formatter ultrarrápido) o black (formatter). El formateo automático no se discute — se configura y se olvida.

Anti-patrones que delatan código amateur

# 1. Excepciones tragadas
try:
    procesar()
except:            # ¿qué falló? ¿por qué? ¿importa?
    pass

# 2. Variables de una letra (fuera de índices matemáticos)
for e in elementos: ...      # ¿e de qué? → elemento

# 3. Números mágicos sin contexto
if edad > 18: ...            # → EDAD_ADULTO = 18

# 4. Funciones de 200 líneas que hacen todo
# → divide: una función, una responsabilidad

# 5. Código muerto comentado
# viejo_codijo_x()   ← bórralo: para eso está git

Estructura de proyecto saludable

• Una responsabilidad por módulo — el nombre del archivo debe decir qué hay adentro
• Funciones cortas (menos de una pantalla): más fáciles de testear y entender
• Constantes arriba, sin valores mágicos esparcidos
• main() como punto de entrada con if __name__ == "__main__": para scripts

Resumen

• snake_case / PascalCase / MAYUSCULAS — cada nombre con su formato
• Docstrings documentan contratos; comentarios explican porqués
• is None, sin == True, líneas cortas — deja que ruff/black lo impongan
• Excepciones específicas, nombres descriptivos, cero números mágicos
• El Zen de Python como criterio: ante la duda, gana lo más legible