44 lines
3.1 KiB
Markdown
44 lines
3.1 KiB
Markdown
# 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 en `camelCase`.
|
|
- `UPPER_SNAKE_CASE` solo para constantes globales reales.
|
|
- Mantener el prefijo `I` para 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.
|
|
|
|
```text
|
|
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.
|