3.1 KiB
Convenciones del proyecto
Idioma y naming
- Código e identificadores en inglés; comentarios, TSDoc y documentación en castellano.
- Ficheros y directorios en
kebab-case. - Clases, tipos e interfaces en
PascalCase; variables, funciones y métodos encamelCase. UPPER_SNAKE_CASEsolo para constantes globales reales.- Mantener el prefijo
Ipara interfaces cuando el área existente lo use.
Las convenciones existentes del área prevalecen sobre introducir una variación aislada.
Principios de diseño
Aplicar pragmáticamente SOLID, Clean Code, DRY, KISS, YAGNI, SSOT, Fail Fast, programación defensiva, inmutabilidad cuando resulte adecuada, idempotencia, menor privilegio y observabilidad en APIs y servicios. Son criterios de diseño, no motivos por sí solos para refactorizar código ajeno ni crear abstracciones prematuras; prevalecen los patrones existentes adecuados y el contexto.
claridad y explicitud
>
abstracción prematura
TypeScript
Preservar la seguridad de tipos. Usar import type para símbolos utilizados exclusivamente como tipos y mantenerlos en la cabecera; no usar imports runtime innecesarios ni referencias inline salvo en .d.ts, module augmentation, código generado o casos técnicamente justificados.
Evitar any; usar unknown cuando el tipo no se conozca. Las assertions y non-null assertions solo proceden con una garantía verificable que TypeScript no pueda inferir. Preferir tipos semánticos, unions o enums existentes y switch exhaustivos; no añadir default si ocultaría casos comprobables. No duplicar tipos derivados de schemas Zod, ni usar Partial<T> cuando el contrato modele la opcionalidad explícitamente. Mantener inmutabilidad cuando no sea necesaria la mutación.
Al cambiar DTOs, schemas, APIs, eventos, modelos persistidos o tipos compartidos, revisar todos sus productores y consumidores.
Comentarios y TSDoc
Los comentarios explican decisiones, riesgos, contratos, efectos laterales, invariantes o limitaciones no evidentes; no traducen el código. Documentar con TSDoc APIs públicas cuando aporte propósito, parámetros, retorno, errores, efectos o restricciones. Tras un refactor se actualizan o eliminan comentarios obsoletos.
Asincronía y errores locales
La regla lint/complexity/noVoid prohíbe usar void para descartar promesas. Toda promesa se espera, se devuelve o gestiona explícitamente con un manejador de error. No dejar promesas flotantes ni silenciar errores con .catch(() => undefined); si un callback debe devolver void, encapsular la operación y gestionar su fallo.
Dependencias y documentación
No añadir ni actualizar dependencias salvo necesidad real: comprobar alternativa existente, justificarla, evaluar mantenimiento, compatibilidad e impacto de bundle o runtime. No modificar lockfiles ni versiones de PNPM incidentalmente, ni introducir supresiones de análisis sin justificación.
La documentación vive en /docs, usa Markdown y nombres en castellano. Debe ser clara, directa y no duplicar fuentes de verdad. Actualizar el documento autoritativo aplicable antes de crear otro equivalente.