Guía de estilo: ARCHITECTURE
TopicFrom the PointSav Documentation
Estándares editoriales para archivos ARCHITECTURE.md en raíces de proyecto en el monorepo de plataforma, cubriendo secciones requeridas, registro técnico, convenciones de diseño de módulo y la disciplina de no-objetivos.
Un archivo ARCHITECTURE.md en la raíz de un proyecto explica la
posición del proyecto dentro del sistema más amplio, la interfaz
que expone, la organización interna de sus módulos y, con igual
importancia, lo que el proyecto no hace. La disciplina de archivos en la raíz rige qué archivos compañeros pueden aparecer junto a ARCHITECTURE.md en la raíz del proyecto.
[edit]Cuándo usar esta plantilla
Se utiliza cuando el diseño del proyecto es suficientemente
complejo como para que un colaborador nuevo no pueda reconstruir
su estructura leyendo únicamente el código fuente. Los proyectos
con más de dos módulos significativos, una decisión de capas no
obvia, o un contrato de consumidor relevante con otras partes
del sistema, requieren un ARCHITECTURE.md.
Las utilidades de un solo archivo y los adaptadores delgados generalmente no lo requieren.
[edit]Estructura requerida
La plantilla exige cuatro secciones en este orden:
- Position — dónde se ubica este proyecto en el sistema más amplio, con referencias a sus pares por nombre canónico.
- Public surface — la API, interfaz o contrato que el proyecto expone al resto del sistema.
- Module layout — árbol de directorios anotado de la organización interna del proyecto.
- What this is not — objetivos explícitamente excluidos, para limitar la interpretación del lector.
[edit]Registro
Técnico. Se asume familiaridad con el dominio. Las oraciones son concisas — promedio de dieciocho palabras, máximo treinta. Se aplica la lista de vocabulario prohibido. Los nombres canónicos del Nomenclature Matrix se usan con exactitud.