KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agent #developer-tools #codex #typescript #cli #deepseek-harness #claude-code #ai-agents #mcp #rust

EURUSConf2026-Rootstack

★ 1 Open GitHub ↗

Repositorio para la exposición "Escribe código hoy que no te dé vergüenza mañana: SoC · KISS · DRY · YAGNI en Python"

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Escribe código hoy que no te dé vergüenza mañana

Material de soporte para la charla técnica **"Escribe código hoy que no te dé vergüenza mañana"**, presentada en el grupo estudiantil **UTPFISC**. Un walkthrough práctico de 4 principios de código limpio a través de un único endpoint real de FastAPI que evoluciona en 4 versiones.

El público objetivo son estudiantes de ingeniería con conocimientos básicos de Python. La idea no es decorar con abstracciones, sino entender cuándo y por qué separar, extraer, simplificar.

## 🚀 Ejecutar el proyecto

### Instalación de dependencias

```bash
uv install
```

### Ejecutar el servidor

```bash
uvicorn main:app --reload
```

Abre tu navegador en `http://localhost:8000/docs` para explorar el Swagger de todas las versiones.

## El endpoint: POST /turnos

Un endpoint simple que reserva un turno académico. **Mismo problema, 4 soluciones**.

### Request

```json
{
  "estudiante_id": "E001",
  "fecha": "2024-12-20",
  "hora": "10:00",
  "motivo": "Consulta sobre proyecto"
}
```

### Response (éxito)

```json
{
  "success": true,
  "mensaje": "Turno confirmado para Ana García",
  "data": {
    "turno_id": "T001",
    "estudiante": "Ana García",
    "fecha": "2024-12-20",
    "hora_inicio": "10:00",
    "hora_fin": "10:30",
    "motivo": "Consulta sobre proyecto",
    "estado": "confirmado"
  }
}
```

### Response (error)

```json
{
  "detail": "El estudiante no está activo"
}
```

## La evolución del código: 4 versiones

### **v0 — El monstruo: todo en un método** 🐉

**Endpoint:** `/v0/turnos`

En v0, el controller es un único método de 90 líneas donde viven todas las responsabilidades:

- Validaciones de formato (fecha, hora)
- Validaciones de negocio (estudiante activo, sin doble turno)
- Lógica de cálculo (hora de fin)
- Generación de IDs
- Guardar en la base de datos
- Formatear la respuesta

```python
@router.post("/turnos")
def reservar_turno(body: TurnoRequest):
    # ← Aquí hay 90 líneas de caos controlado
    if "estudiante_id" not in body:
        return {"error": "estudiante_id es requerido"}
    # ... más validaciones, cálculos, lógica ...
    turno_id = f"T{str(len(turnos_db) + 1).zfill(3)}"
    turnos_db.append(nuevo_turno)
    return TurnoResponse(...)
```

**El problema:** El método hace demasiadas cosas. Si necesitas entender por qué un turno falla, tenés que leer todo. Si necesitas agregar una validación, no sabés dónde ponerla. Si necesitas reutilizar la lógica, copiás y pegás.

**El síntoma:** "¿Alguien entiende esta función?"

---

### **v1 — Separation of Concerns: cada cosa en su lugar** 🎯

**Endpoint:** `/v1/turnos`

**Principio:** Una función/clase debe tener una sola razón para cambiar.

En v1 separamos las responsabilidades:

- **Router** (controller): Recibe → delega → responde (3 líneas)
- **TurnoValidator**: Solo valida
- **TurnoService**: Solo crea turnos (lógica de negocio)
- **TurnoHelper**: Solo calcula cosas puras

```python
# Router — el controller queda microscópico
@router.post("/turnos", response_model=TurnoResponse)
def reservar_turno(body: TurnoRequest) -> TurnoResponse:
    validator.validar(body)
    turno = service.crear_turno(body)
    return TurnoResponse(...)
```

```python
# Validator — solo valida, lanza excepciones si algo está mal
class TurnoValidator:
    def validar(self, data: TurnoRequest):
        self._validar_fecha(data.fecha)
        self._validar_hora(data.hora)
        self._validar_estudiante(data.estudiante_id)
        self._validar_disponibilidad(...)
```

```python
# Service — orquesta la lógica sin mezclar responsabilidades
class TurnoService:
    def crear_turno(self, data: TurnoRequest) -> dict:
        estudiante = estudiantes_db[data.estudiante_id]
        turno = {
            "id": self.helper.generar_id(),
            "hora_fin": self.helper.calcular_hora_fin(data.hora),
            ...
        }
        turnos_db.append(turno)
        return turno
```

**Lo que ganamos:** Código más legible. Cada clase tiene una responsabilidad clara. Si algo falla, sabés dónde buscar. Si necesitas cambiar la lógica de validación, vas a `TurnoValidator`.

**El lado oscuro:** Separar por separar es overengineering. En v1 tenemos clases que no tienen estado (`TurnoValidator` es un contenedor de métodos que podrían ser funciones). Agregamos capas de indirección. ¿Para qué? Todavía no lo justificamos bien.

**La pregunta para tu código:** ¿Tiene una sola razón de existir? ¿O hace validar, calcular, guardar y responder todo junto?

---

### **v2 — Don't Repeat Yourself: la regla de las 3 repeticiones** 🔄

**Endpoint:** `/v2/turnos`

**Principio:** No abstraigas a la primera ni a la segunda repetición. A la tercera, tenés evidencia.

En v1 notamos que `parsear_fecha()` y `parsear_hora()` aparecían en:

1. `TurnoValidator._validar_fecha()` 
2. `TurnoValidator._validar_hora()` 
3. (Potencialmente) En el service o helpers si necesitaban procesar las fechas

En lugar de abstraer a la primera copia, esperamos a la tercera. Cuando la vimos, creamos `utils.py`:

```python
# utils.py — funciones reutilizables
def parsear_fecha(fecha: str) -> datetime:
    try:
        return datetime.strptime(fecha, "%Y-%m-%d")
    except ValueError:
        raise HTTPException(400, "Formato de fecha inválido, use YYYY-MM-DD")

def parsear_hora(hora: str) -> datetime:
    try:
        return datetime.strptime(hora, "%H:%M")
    except ValueError:
        raise HTTPException(400, "Formato de hora inválido, use HH:MM")

def get_estudiante_o_404(estudiante_id: str) -> dict:
    if estudiante_id not in estudiantes_db:
        raise HTTPException(404, f"Estudiante {estudiante_id} no encontrado")
    return estudiantes_db[estudiante_id]
```

Ahora `TurnoValidator` las usa:

```python
def _validar_fecha(self, fecha: str):
    dt = parsear_fecha(fecha)  # ← Reutilizable
    if dt.date() < datetime.today().date():
        raise HTTPException(...)
```

**Lo que ganamos:** Sin duplicación. La lógica de "convertir string a fecha" vive en un solo lugar.

**Por qué esperamos a la tercera:** Las primeras dos repeticiones pueden ser coincidencia. La función que extraes a la segunda vez probablemente necesitará cambios cuando la veas por tercera vez, y terminarás reescribiendo. Esperar reduce falsos positivos.

**El lado oscuro de DRY:** Abstraer demasiado pronto causa overengineering. "DRY" no significa "sin duplicación nunca". Significa "sin duplicación *innecesaria*". Tres líneas idénticas en v0 y v1? Diferentes contextos → sin abstraer. Tres ocurrencias genuinas en el mismo problema? Abstraer.

**La pregunta para tu código:** ¿Esta lógica aparece por tercera vez? ¿O estás abstracto porque "podría reutilizarse"?

---

### **v3 — KISS + YAGNI: simplicidad sin imaginaciones** ⚡

**Endpoint:** `/v3/turnos`

**Principios:**
- **KISS (Keep It Simple, Stupid):** Si algo no necesita estado, usa funciones, no clases.
- **YAGNI (You Ain't Gonna Need It):** Construí para el problema de hoy, no para los "qué pasaría si" de mañana.

En v1 y v2, tenemos clases sin estado:

```python
# v1: TurnoValidator es una clase sin estado
class TurnoValidator:
    def validar(self, data):
        # self no se usa en ningún lado
```

```python
# v1: TurnoHelper también es una clase sin estado
class TurnoHelper:
    @staticmethod
    def calcular_hora_fin(hora: str) -> str:
        # @staticmethod → esto no necesita la clase
```

```python
# v1: TurnoService tiene __init__ pero no guarda estado
class TurnoService:
    def __init__(self):
        self.helper = TurnoHelper()  # ¿Para qué?
```

En v3, convertimos esas clases a funciones:

```python
# v3: Validaciones como funciones
def validar_turno(data: TurnoRequest):
    _validar_fecha(data.fecha)
    _validar_hora(data.hora)
    _validar_estudiante(data.estudiante_id)
    _validar_disponibilidad(data.fecha, data.hora, data.estudiante_id)
```

```python
# v3: Service como función
def crear_turno_service(data: TurnoRequest) -> dict:
    estudiante = get_estudiante_o_404(data.estudiante_id)
    hora_fin = (parsear_hora(data.hora) + timedelta(minutes=DURACION_MINUTOS)).strftime("%H:%M")
    turno_id = f"T{str(len(turnos_db) + 1).zfill(3)}"
    turno = {...}
    turnos_db.append(turno)
    return turno
```

```python
# v3: El controller sigue siendo simple
@router.post("/turnos", response_model=TurnoResponse)
def reservar_turno(body: TurnoRequest) -> TurnoResponse:
    validar_turno(body)
    turno = crear_turno_service(body)
    return TurnoResponse(...)
```

**Lo que ganamos:** Código más directo. Sin clases de "contenedor". Sin `__init__` innecesarios. Sin overhead mental.

**YAGNI en acción:** En v1 y v2, podríamos haber pensado:
- "¿Y si en el futuro tenemos tipos de turno diferentes?"
- "¿Y si necesitamos una clase `TurnoRepository` para abstraer la base de datos?"
- "¿Y si agregamos un campo `prioridad` al turno?"

En v3, **no lo hicimos**. Porque nadie lo pidió. YAGNI es tu brújula contra el overengineering.

**El lado oscuro de KISS:** No es excusa para no estructurar. V3 sigue siendo separado (validator, service, dtos). No es el caos de v0. Es estructura sin ceremonia.

**La pregunta para tu código:** ¿Esta clase tiene estado? ¿O es un contenedor de funciones con pretensiones? ¿Necesito esta lógica hoy, o la estoy escribiendo para un "qué pasaría si"?

---

## La regla de las 3 repeticiones

Es el concepto más accionable de la charla. Úsalo en tu código a partir de hoy.

**La regla:**
1. Primera vez que ves duplicación → No abstraigas. Puede ser coincidencia.
2. Segunda vez → Observa. Pero no abstraigas aún.
3. Tercera vez → Tenés prueba real de un patrón. Ahora sí, extrae.

**Por qué funciona:**
- Las primeras dos veces, los contextos pueden ser diferentes.
- A la tercera, se ve el patrón genuino.
- Abstraer antes causa falsos positivos y abstracciones que cambiarás luego.

**Ejemplo real:**

En v0 tenemos:

```python
try:
    fecha = datetime.strptime(body["fecha"], "%Y-%m-%d")
except ValueError:
    return {"error": "Formato de fecha inválido..."}
```

En v1, lo vemos en `_validar_fecha()`. Podríamos haberlo abstraído ahí. **No lo hicimos.**

En v2, lo vemos nuevamente (en service, si procesa fechas). Ahora sí → creamos `parsear_fecha()`.

Abstraer en v1 hubiera sido precipitado. Esperar a v2 eliminó falsos positivos.

---

## Tabla resumen: el viaje de v0 a v3

| Versión | Principio | Responsabilidades | Líneas totales | Líneas del controller | Problema resuelto |
|---------|-----------|-------------------|---------------|-----------------------|-------------------|
| **v0**  | Ninguno   | Todo en uno       | ~90            | 90                    | Código legible |
| **v1**  | SoC       | 4 capas            | ~150           | 3                     | Código confuso |
| **v2**  | SoC + DRY | 4 capas + utils    | ~140           | 3                     | Duplicación |
| **v3**  | SoC+DRY+KISS+YAGNI | 4 capas, sin clases vacías | ~120 | 3 | Overengineering |

**Nota:** v3 tiene menos líneas que v2 porque eliminamos clases innecesarias. v1 tiene más porque estamos siendo explícitos en la separación.

---

## Las 4 preguntas clave

Úsalas en code review, en tu propio código, en cualquier parte:

### 1️⃣ SoC — ¿Tiene una sola razón de existir?

**Pregunta:** Si tengo que describir qué hace esta función/clase en una frase corta, ¿puedo hacerlo sin "y"?

- ❌ "Validar, calcular y guardar"
- ✅ "Validar datos de entrada"
- ✅ "Calcular la hora de fin"
- ✅ "Guardar el turno"

Si necesitas "y", probablemente tenga más de una responsabilidad.

### 2️⃣ DRY — ¿Apareció 3 veces?

**Pregunta:** Antes de extraer esto a una función, ¿he visto este patrón exacto en 3 lugares diferentes del código?

- Primera vez → Observa
- Segunda vez → Sigue observando
- Tercera vez → Extrae

Si estás abstrayendo en la primera o segunda vez, pregúntate: "¿Seguro que esto va a repetirse?"

### 3️⃣ KISS — ¿Se entiende de un vistazo?

**Pregunta:** Si alguien lee este código por primera vez, ¿le lleva menos de 1 minuto entender qué hace?

- ❌ Clases con estado complejo
- ❌ Métodos con 50+ líneas
- ❌ Variables con nombres como `x`, `tmp`, `data2`
- ✅ Nombres claros
- ✅ Funciones que hacen una cosa
- ✅ Sin trucos de "lo sé porque trabajé 2 años en este código"

KISS no es "hacerlo simple al costo de no estructurar". Es "estructura clara, sin complejidad innecesaria".

### 4️⃣ YAGNI — ¿Lo necesito hoy?

**Pregunta:** Si nunca lo uso, ¿el código sigue funcionando?

- ❌ "Agregamos un campo `tipo_turno` porque en el futuro podría haber diferentes tipos"
- ❌ "Creamos una clase `TurnoRepository` para cuando cambiar la BD"
- ✅ "Agregamos validación para lo que el usuario solicitó hoy"
- ✅ "Guardamos en memoria porque eso es lo que necesitamos ahora"

Mañana el usuario pedirá algo diferente. YAGNI dice: "Construí para hoy, refactoriza mañana."

---

## Estructura del repositorio

```
.
├── main.py                 # App FastAPI con todos los routers
├── const.py                # Base de datos fake + constantes compartidas
│
├── v0/                     # v0: El monstruo (todo en router.py)
│   └── router.py
│
├── v1/                     # v1: Separation of Concerns
│   ├── router.py           # Controller
│   ├── dtos.py             # Modelos Pydantic
│   ├── turno_validator.py  # Validaciones
│   ├── turno_service.py    # Lógica de negocio
│   ├── turno_helper.py     # Funciones puras
│   └── __init__.py
│
├── v2/                     # v2: + Don't Repeat Yourself
│   ├── router.py
│   ├── dtos.py
│   ├── turno_validator.py
│   ├── turno_service.py
│   ├── turno_helper.py
│   ├── utils.py            # ← Helpers extraídos (parsear_fecha, etc.)
│   └── __init__.py
│
└── v3/                     # v3: + KISS + YAGNI
    ├── router.py
    ├── dtos.py
    ├── validations.py      # ← Funciones, no clases
    ├── services.py         # ← Funciones, no clases
    ├── utils.py            # Reutilizable desde v2
    └── __init__.py
```

---

## Cómo leer el código

**Para estudiantes nuevos:**
1. Empieza en **v0/router.py**. Lee el código de arriba a abajo. Entiende el "por qué" de cada sección.
2. Luego, **v1/router.py**. Nota cómo el controller se reduce a 3 líneas. Lee `turno_validator.py` y `turno_service.py`.
3. **v2/utils.py**. Entiende qué funciones se extrajeron y por qué (la 3ª repetición).
4. **v3/** . Nota que `TurnoValidator` y `TurnoService` se convirtieron a funciones.

**Para code review:**
- ¿Tu función hace más de una cosa? → Mira v1.
- ¿Hay duplicación? Espera la 3ª repetición → Mira v2.
- ¿Tu clase no tiene estado? → Mira v3.

**Para entender los principios:**
- SoC: Compara v0 (caos) con v1 (separado).
- DRY: Compara v1 (con duplicación) con v2 (helpers extraídos).
- KISS: Compara v1 (clases sin estado) con v3 (funciones).
- YAGNI: Nota que en v3 no agregamos lógica para "futuros tipos de turno".

---

## Recursos para seguir aprendiendo

- **"Clean Code" (Robert C. Martin).** El clásico. Si quieres entender SoC a fondo, los primeros capítulos son obligatorios.
- **[Refactoring.Guru](https://refactoring.guru)** — Gratis, en español. Patrones de refactoring con ejemplos visuales.
- **"AHA Programming" (Kent C. Dodds).** El antídoto a DRY mal aplicado. Diferencia entre "no repetir" y "sobre-abstraer".

---

## Notas para instructores

Esta charla funciona como walkthrough vivo. Ideal presentar saltando entre versiones:

1. Abre v0 en Swagger, testea el endpoint.
2. Explica por qué es difícil de leer (90 líneas en una función).
3. Muestra v1: el mismo endpoint, pero con controller de 3 líneas.
4. Pregunta: "¿Ven cómo cambió el código pero no la funcionalidad?"
5. Introduce v2: "¿Notan la duplicación?" Muestra v2/utils.py.
6. Introduce v3: "¿Estas clases necesitaban serlo?" Explica KISS y YAGNI.

**Timing sugerido:** 30-40 minutos para la charla en vivo. Pueden jugar con el Swagger en paralelo.

---

**Escrito para UTPFISC. Si algo no está claro, ese es el bug — el código debe hablar por sí solo.**

EURUSConf2026-Rootstack

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README