David
0e7106f30c
- Updated "Ficha del proyecto UECKO.md" to clarify architectural boundaries and continuity rules. - Revised "README.md" to enhance structure and clarify sources of truth for documentation. - Improved "backend.md" with clearer definitions of responsibilities and architectural layers. - Streamlined "convenciones.md" to emphasize naming conventions and TypeScript best practices. - Enhanced "datos-persistencia.md" to specify persistence rules and data integrity measures. - Updated "frontend.md" to define frontend rules and state management practices. - Refined "testing.md" to clarify testing levels and validation processes. - Revised "vision-general.md" to outline system architecture and module boundaries more clearly.
2.6 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.
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.