Cultura de Revisión de Código
La revisión de código es el principal bucle de enseñanza del equipo para la artesanía en Python: tipos, trampas asíncronas, seguridad SQL y lagunas de pruebas. Una cultura de alta señal significa estándares claros, retroalimentación respetuosa y plazos de entrega predecibles, no un perfeccionismo que bloquea la entrega.
Receta
Tarjeta de receta de referencia rápida, lista para copiar y pegar.
## Plantilla de descripción de PR
**Intención:** una frase
**Riesgo:** indicador de migración / rendimiento / seguridad
**Evidencia de prueba:** ruta de pytest, captura de pantalla, nota de carga
**Reversión:** plan de indicador o reversión
## Niveles de comentarios de revisión
🔴 Debe arreglarse - corrección, seguridad, pérdida de datos
🟡 Debería arreglarse - claridad, prueba faltante (el autor puede posponer con un ticket)
🟢 Detalle menor - estilo; a discreción del autorCuándo recurrir a esto:
- La latencia de las revisiones supera rutinariamente las 24 horas
- Las revisiones son guerras de estilo sin enseñanza
- Los juniors temen publicar PRs
- Los incidentes se rastrean hasta verificaciones de revisión omitidas
Ejemplo de Trabajo
# El autor aborda la revisión con un comentario de intercambio explícito
# REVISIÓN: se mantuvo el ORM síncrono aquí intencionalmente - RFC-042 fase 1 de solo lectura.
# La migración asíncrona se rastrea en ENG-4412.
def get_catalog_item(item_id: str) -> dict[str, object]:
...## Lista de verificación del revisor (Python)
- [ ] Tipos en funciones públicas / modelos Pydantic validados
- [ ] No hay I/O bloqueante en async def sin asyncio.to_thread
- [ ] Consultas a la base de datos parametrizadas; sin concatenación de SQL con cadenas
- [ ] Las pruebas cubren la ruta feliz + un modo de fallo
- [ ] El registro está estructurado; sin PII en los mensajesLo que esto demuestra:
- La intención y el riesgo de la PR son visibles antes de leer la diferencia
- Los niveles de comentarios separan los bloqueadores de los detalles menores
- El trabajo diferido se vincula a un ticket, no a bucles de revisión interminables
- La lista de verificación específica de Python captura problemas comunes en toda la flota
Inmersión Profunda
Cómo Funciona
- Responsabilidad del autor - Diferencias pequeñas, autoevaluación, pruebas ejecutadas localmente con
uv run pytest. - Responsabilidad del revisor - Responder dentro del SLA; hacer preguntas antes de prescribir reescrituras.
- Enseñanza - Enlace a la documentación interna o página de SME al sugerir un patrón.
- Rotación - Distribuir el conocimiento del dominio; evitar un único guardián.
- Automatización - Ruff, mypy/pyright y los escáneres de seguridad manejan problemas mecánicos.
Directrices del SLA de Revisión
| Tamaño de la PR | Respuesta inicial objetivo |
|---|---|
| < 200 LOC | Mismo día hábil |
| 200-500 LOC | 24 horas |
| > 500 LOC | El autor debería dividir |
Notas de Python
# pyproject.toml - dejar que CI aplique el estilo para que la revisión se centre en el diseño
[tool.ruff]
line-length = 100
select = ["E", "F", "I", "UP", "B", "ASYNC"]Trampas
- LGTM sin leer las pruebas - Se envían regresiones. Solución: Requerir evidencia de prueba en la plantilla de PR.
- Comentarios de detalles menores como bloqueadores - La moral y la velocidad mueren. Solución: Usar el nivel 🟢; agrupar los detalles menores una vez.
- PRs gigantes - Nadie revisa en profundidad. Solución: Dividir por indicador de función o porción vertical.
- El revisor reescribe todo el parche - El autor aprende poco. Solución: Sugerir la dirección + enlace al ejemplo.
- Solo los seniors revisan - El factor de autobús crece. Solución: Emparejar a un revisor junior con un senior en cambios grandes.
Alternativas
| Alternativa | Usar Cuándo | No Usar Cuándo |
|---|---|---|
| Programación en parejas | Código nuevo complejo | CRUD simple con pruebas |
| Sesión de revisión en grupo | Cambio de arquitectura | PRs pequeñas diarias |
| Bots de aprobación automática | Error tipográfico en documentación | Lógica de aplicación |
| Inspección formal | Seguridad regulada | Velocidad normal del producto |
Preguntas Frecuentes
¿Cuántos revisores se requieren?
Uno para lo rutinario; dos para seguridad, migraciones o bibliotecas compartidas.
¿Deberían los revisores ejecutar el código localmente?
Para cambios arriesgados sí; de lo contrario, confíe en CI si las pruebas son exhaustivas.
¿Cómo manejar revisiones en desacuerdo?
El autor responde con el razonamiento; escalar al líder técnico si hay un punto muerto.
¿Revisar migraciones asíncronas especialmente?
Sí - verificar el bloqueo del bucle, la configuración del pool y el indicador de reversión.
Comentarios sobre código generado?
Revisar las entradas y plantillas del generador, no cada línea de salida.
¿Cómo revisar notebooks?
Centrarse en la fuga de datos, la no determinismo y la ruta de promoción a producción.
¿Límites de tamaño de PR?
Límite blando de 400 LOC cambiados; las excepciones necesitan enlace RFC.
¿Revisar el propio código?
Nunca ser el único aprobador; el autor puede fusionar solo después de la aprobación de otro.
¿Cómo medir la salud de la revisión?
Tiempo hasta la primera revisión, relación de niveles de comentarios, tasa de defectos posteriores a la fusión.
¿Revisión asistida por LLM?
Usar para pasar la lista de verificación; el humano es responsable de la seguridad y la corrección del dominio.
Relacionados
- Mentoría y Niveles - revisiones como enseñanza
- Ejecución de Revisiones de Diseño - antes de PRs grandes
- Manejo de Desacuerdos Técnicos - puntos muertos
- Linting y Formateo - automatizar detalles menores
- Pruebas con pytest - expectativas de prueba
Versiones de Stack: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, y uv 0.6+.