Estándares de Código
Convenciones acordadas que reducen la fricción y permiten la propiedad colectiva.
1Por qué Importan los Estándares
Los estándares de código son acuerdos del equipo sobre cómo debe escribirse el código:
- Convenciones de nomenclatura (camelCase vs snake_case)
- Formato (tabulaciones vs espacios, ubicación de llaves)
- Organización del código (estructura de archivos, límites de módulos)
- Patrones (cómo manejar errores, cómo estructurar pruebas)
Los estándares permiten la propiedad colectiva. Cuando el código se ve igual en todas partes, cualquiera puede leer cualquier código. No hay "traducción" entre el estilo de Bob y el estilo de Alice.
Los estándares también reducen la fricción en la revisión de código. En lugar de debatir el formato, discutes la lógica y el diseño. Las discusiones triviales desaparecen.
Sin estándares: Cada archivo se siente diferente. Moverse entre módulos requiere cambio de contexto mental. La revisión de código se convierte en una guerra de estilos.
Con estándares: La base de código se siente unificada. Leer código desconocido es más fácil. Las revisiones se enfocan en lo que importa.
El estándar específico importa menos que tener un estándar. Elige algo razonable y apégate a ello.
2Estándares vs Estilo
No todas las convenciones son iguales. Distingue entre:
Estándares semánticos: Afectan el comportamiento del código o la mantenibilidad
- Patrones de manejo de errores
- Convenciones de registro
- Estructura de pruebas
- Patrones de diseño de API
Estándares estilísticos: Afectan solo la apariencia
- Formato (indentación, longitud de línea)
- Nomenclatura (camelCase vs snake_case)
- Ubicación de llaves
Los estándares semánticos merecen discusión. Cómo el equipo maneja los errores es una decisión significativa con consecuencias reales.
Los estándares estilísticos deben automatizarse. Usa Prettier, Black, gofmt—herramientas que formatean código automáticamente. No desperdicies tiempo humano en tabulaciones vs espacios.
El objetivo es eliminar la fricción, no lograr algún ideal platónico de estilo de código.
3Aplicación Automatizada
Las herramientas modernas pueden aplicar la mayoría de los estándares automáticamente:
Formateadores: Prettier (JavaScript), Black (Python), gofmt (Go), rustfmt (Rust)
- Se ejecutan al guardar o como un hook pre-commit
- Eliminan completamente las discusiones de formato
Linters: ESLint, Pylint, Clippy, RuboCop
- Detectan violaciones de estilo y errores potenciales
- Configurables según las preferencias del equipo
- Se ejecutan en CI para evitar que código no conforme se fusione
Verificadores de tipos: TypeScript, mypy, Flow
- Aplican consistencia de tipos
- Detectan errores antes de la ejecución
Hooks pre-commit: Husky, pre-commit
- Ejecutan verificaciones antes de que el código se confirme
- Detectan problemas antes de que entren al repositorio
Configura una vez, aplica para siempre. No dependas de la disciplina humana—automatízalo.
El equipo usa Prettier con una configuración compartida. Cada commit activa el formato. La revisión de código nunca menciona el formato—solo se enfoca en la lógica y el diseño.
El equipo tiene una guía de estilo de 50 páginas. Los revisores pasan la mitad de su tiempo señalando violaciones de estilo. Los desarrolladores resienten las críticas menores. Los nuevos miembros del equipo luchan por aprender todas las reglas.
4Establecer Estándares Sin Guerras Religiosas
Los estándares pueden desencadenar opiniones fuertes. Evita debates interminables:
Comienza con convenciones existentes. Si el lenguaje o framework tiene un estilo estándar (Go, Rust), simplemente úsalo. No reinventes.
Usa valores predeterminados de la industria. Las configuraciones populares de linter/formateador (Airbnb ESLint, guía de estilo de Google) están probadas en batalla.
Decide rápido, ajusta después. Elige algo razonable. Si resulta problemático, cámbialo. No bloquees el progreso esperando el estándar perfecto.
Hazlo democrático pero decisivo. Deja que el equipo vote sobre temas polémicos. Gana la mayoría. La minoría acepta la decisión.
Recuerda el objetivo. Los estándares existen para reducir la fricción, no para expresar preferencias. Si una discusión está tomando demasiado tiempo, cualquier elección razonable está bien.
No Optimices Prematuramente
Pasar una semana debatiendo puntos y comas no es un buen uso del tiempo. Elige un formateador y sigue adelante.
5Documentación Viva
Los estándares deben documentarse—pero mantenlos vivos:
Qué documentar:
- Estándares semánticos (cómo manejar errores, patrones de prueba)
- Justificación para elecciones no obvias (por qué elegimos X sobre Y)
- Excepciones y cuándo romper las reglas
- Cómo proponer cambios
Dónde documentar:
- Archivo README o CONTRIBUTING en el repositorio
- Wiki o espacio de documentación del equipo
- Comentarios en la configuración del linter/formateador
Mantenla actualizada. La documentación desactualizada es peor que ninguna documentación. Cuando cambies un estándar, actualiza los documentos.
Hazla encontrable. Los nuevos miembros del equipo deben encontrar los estándares fácilmente. No los entierres en un laberinto de wiki.
La mejor documentación es el código mismo. Si tus estándares se aplican automáticamente, el código demuestra qué es aceptable.
- Los estándares permiten la propiedad colectiva al hacer que todo el código sea legible
- Automatiza la aplicación estilística—no desperdicies tiempo humano en formato
- Los estándares semánticos (patrones, manejo de errores) merecen discusión
- Elige valores predeterminados razonables rápidamente; no dejes que los debates bloqueen el progreso
- Documenta los estándares y mantén la documentación actualizada
- •Debates interminables sobre formato (automatízalo en su lugar)
- •Aplicación manual que desperdicia tiempo de revisión
- •Ignorar estándares en 'arreglos rápidos' que se vuelven permanentes
- •Documentación desactualizada que no coincide con la realidad