Convenciones de Codigo¶

Naming¶

Archivos: snake_case.py
Clases: PascalCase
Funciones/metodos: snake_case
Constantes: UPPER_SNAKE_CASE
Variables privadas: _prefijo_underscore
Type vars: T, E, ResponseT

Imports¶

Orden (ruff I lo fuerza): 1. Standard library 2. Third-party 3. Local application

from __future__ import annotations

import os
import re
from dataclasses import dataclass

from returns.result import Failure, Result, Success

from mi_proyecto.core.entities import Document

Error Handling¶

Result Pattern (obligatorio para logica de negocio)¶

from returns.result import Result, Success, Failure

def process(data: str) -> Result[ProcessedData, str]:
    if not data:
        return Failure("Datos vacios")
    return Success(ProcessedData(data=data))

Exceptions (solo para errores irrecuperables)¶

# BIEN — error de infraestructura, logged
try:
    connection = db.connect()
except ConnectionError:
    logger.error("No se pudo conectar a BD", exc_info=True)
    raise

# MAL — nunca hacer esto
try:
    something()
except:
    pass

Logging¶

from mi_proyecto.infrastructure.logging import get_logger

logger = get_logger(__name__)

# Niveles
logger.debug("Detalle tecnico para debugging")
logger.info("Evento de negocio relevante")
logger.warning("Situacion inesperada pero recuperable")
logger.error("Error que afecta funcionalidad", exc_info=True)

NUNCA: logging.getLogger(), print() para debugging, logger.exception() fuera de except.

DTOs y Value Objects¶

from dataclasses import dataclass

@dataclass(frozen=True)
class CreateUserRequest:
    """DTO para creacion de usuario."""
    name: str
    email: str
    role: str = "viewer"

Siempre frozen=True — inmutabilidad previene bugs de estado compartido.

Type Hints¶

Obligatorios en todo codigo de produccion:

def find_user(user_id: int) -> User | None:
    ...

def process_items(items: list[Item]) -> Result[Summary, str]:
    ...

Commits¶

Formato: tipo(alcance): descripcion en espanol

Tipos validos: - feat: nueva funcionalidad - fix: correccion de bug - refactor: cambio sin alterar comportamiento - docs: solo documentacion - test: solo tests - chore: mantenimiento (deps, config, CI)

Ejemplos:

feat(auth): implementar login con JWT
fix(search): corregir paginacion cuando offset > total
refactor(core): extraer validacion a value object
docs(planning-5): documentar decision de arquitectura
test(dedup): agregar property tests para hash

Sin firma Claude/Anthropic en commits.

Seguridad¶

SQL: Siempre parameterizado (?, %s). Whitelists para nombres de tabla/columna dinamicos.
HTML: Escapar todo output de usuario.
Archivos: Validar paths, nunca construir desde input de usuario sin sanitizar.
Secrets: Nunca hardcoded. Variables de entorno o archivos .env (.gitignored).