PEP 8 en Python: guía para escribir código limpio

PEP 8 en Python es la guía de estilo más conocida del lenguaje. Su objetivo no es cambiar lo que hace un programa, sino facilitar que otras personas —y tu yo del futuro— comprendan el código. Las convenciones cubren nombres, sangría, espacios, imports, longitud de líneas, funciones, clases y organización general.

La fuente principal es la PEP 8 oficial. No todas sus recomendaciones son reglas absolutas: la coherencia del proyecto y la legibilidad tienen prioridad cuando existe una razón clara.

Sangría de cuatro espacios

def calcular_total(precios):
    total = 0.0

    for precio in precios:
        total += precio

    return total

Python utiliza la sangría como parte de la sintaxis. Configura el editor para insertar cuatro espacios y evita mezclar tabulaciones con espacios.

Nombres claros

• Funciones y variables: snake_case.
• Clases: CapWords o PascalCase.
• Constantes: MAYUSCULAS_CON_GUIONES.
• Módulos: nombres cortos en minúsculas.

MAX_INTENTOS = 3

class GestorUsuarios:
    def buscar_usuario(self, usuario_id):
        ...

Los nombres deben explicar la intención. Evita abreviaturas ambiguas como x1, tmp2 o data_final_final.

Espacios alrededor de operadores

# Recomendado
subtotal = cantidad * precio
total = subtotal + impuesto

# Difícil de leer
subtotal=cantidad*precio

No añadas espacios inmediatamente dentro de paréntesis, corchetes o llaves.

Imports organizados

import json
from pathlib import Path

import pandas as pd

from mi_proyecto.configuracion import cargar_configuracion

Separa imports de la biblioteca estándar, dependencias externas y módulos locales. Normalmente cada import ocupa su propia línea.

Evitar imports con asterisco

# Evita
from modulo import *

# Mejor
from modulo import funcion_a, funcion_b

Los imports explícitos muestran de dónde viene cada nombre y reducen colisiones.

Longitud de líneas

PEP 8 recomienda líneas moderadas. Cuando una expresión crece, divide dentro de paréntesis:

resultado = procesar_datos(
    origen=ruta_origen,
    destino=ruta_destino,
    validar=True,
    sobrescribir=False,
)

Evita barras invertidas para continuar líneas cuando los paréntesis ofrecen una alternativa más clara.

Líneas en blanco

Las líneas en blanco separan ideas. Usa dos entre definiciones de nivel superior y una entre métodos o bloques lógicos dentro de una función, sin fragmentar excesivamente el código.

Comparaciones con None y booleanos

if resultado is None:
    print("Sin resultado")

if usuario_activo:
    print("Usuario activo")

Usa is None en lugar de == None. Para booleanos, normalmente no necesitas comparar con True. La guía de None en Python y la de booleanos en Python amplían estas prácticas.

Funciones pequeñas y enfocadas

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


def aplicar_descuento(subtotal, porcentaje):
    return subtotal * (1 - porcentaje)

Una función con una responsabilidad clara es más fácil de nombrar, probar y documentar. Consulta la guía de funciones en Python.

Comentarios que expliquen el motivo

# El proveedor limita cada solicitud a 100 registros.
TAMANO_LOTE = 100

Un comentario útil explica una decisión, una limitación o un contexto que el código no puede expresar por sí solo. No repitas literalmente cada línea. La guía de comentarios en Python muestra ejemplos.

Docstrings para interfaces públicas

def calcular_promedio(valores):
    """Devuelve el promedio de una secuencia no vacía."""
    return sum(valores) / len(valores)

Los docstrings documentan módulos, clases, funciones y métodos. La guía de docstrings en Python explica formatos y herramientas.

Excepciones específicas

try:
    edad = int(texto)
except ValueError:
    print("La edad debe ser un número entero")

Evita except: sin tipo, porque también captura eventos que normalmente deben propagarse. La guía de try y except explica cómo manejar errores con precisión.

Refactorización práctica

Código difícil de leer:

def f(x,y,z=False):
    r=[]
    for i in x:
        if i>y and not z:r.append(i*2)
    return r

Versión más clara:

def duplicar_mayores(
    valores,
    limite,
    omitir_resultados=False,
):
    resultados = []

    for valor in valores:
        if valor > limite and not omitir_resultados:
            resultados.append(valor * 2)

    return resultados

La segunda versión ocupa más líneas, pero comunica nombres, condiciones y estructura.

Automatizar comprobaciones

Los linters detectan problemas de estilo, imports no utilizados y errores comunes. Ruff reúne comprobaciones y correcciones rápidas; su documentación oficial explica instalación y configuración.

python -m pip install ruff
ruff check .
ruff format .

Guarda la configuración en pyproject.toml para que todo el equipo utilice las mismas reglas.

PEP 8 y formatters

Un formatter resuelve automáticamente decisiones mecánicas, pero no elige buenos nombres ni divide responsabilidades. Combina formato automático, linting, pruebas y revisión humana.

Cuándo apartarse de la guía

• Compatibilidad con una API pública existente.
• Convenciones establecidas por un framework.
• Código generado automáticamente.
• Expresiones matemáticas o tablas donde otra disposición mejora la lectura.

Documenta la decisión y mantén consistencia local.

Lista de revisión

• ¿Los nombres expresan la intención?
• ¿La sangría es consistente?
• ¿Los imports están organizados?
• ¿Las funciones tienen responsabilidades pequeñas?
• ¿Los comentarios explican motivos?
• ¿Las excepciones son específicas?
• ¿El linter y el formatter usan una configuración compartida?

Conclusión

PEP 8 en Python proporciona un vocabulario común para escribir código legible. No se trata de obedecer una lista de reglas de forma ciega, sino de reducir sorpresas y facilitar el mantenimiento. Automatiza el formato, utiliza un linter y dedica la revisión humana a nombres, diseño y claridad.