
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 Ao longo dos anos, traballei en todo tipo de proxectos — grandes, pequenos, caóticos, sobredimensionados, "temporais", aparentemente ben estruturados e todo o que hai entre medias. E aínda así, un patrón foi hilarantemente consistente: A documentación sempre está ausente, desactualizada ou enterrada nalgunha esquina esquecida de Confluence, protexida por unha marca de tempo de 2019. Cada proxecto   ter documentación. afirma Cada equipo   que a manterá actualizada. promete E cada programador di con confianza: "Non te preocupes, escribireino máis tarde", que, como todos sabemos, é o equivalente en documentación a dicir  "o cheque está no correo". Despois de ver este ciclo repetirse máis veces do que me gustaría admitir, decateime de algo sinxelo pero brutalmente certo: 
 
 A documentación só sobrevive se vive o máis preto posible do código — porque os programadores (incluíndome a min) somos criaturas preguiceiras. E a partir diso, veu outra conclusión: o principal problema da documentación desactualizada é o feito de que a maioría dos equipos non a consideran parte do ciclo de desenvolvemento principal, deixándoa para máis tarde ou conformándose con un par de especificacións previas ao desenvolvemento que xa tiñan nalgún lugar de Confluence. Para escribir documentación significativa, discutamos primeiro que tipo de documentación existe para un compoñente de software: Formas de Documentar Código (Que os Programadores Poderían Realmente Usar) Unha vez que aceptas que a documentación ten que vivir preto do código, a seguinte pregunta é   estruturala. como Na práctica, descubrín que unha boa documentación non é un único artefacto — é un pequeno ecosistema de capas, cada unha servindo a un propósito e audiencia diferente. Para ese proxecto que mencionei (escrito en Java + Spring Boot), identificamos catro tipos principais de documentos: 1. Especificacións do Cliente Son documentos convencionais xeralmente compilados por un experto no dominio. Idealmente, son ricos en linguaxe ubicua e proporcionan descricións agnósticas ao código de casos de negocio — noutras palabras, todo o que un enxeñeiro necesita para comprender verdadeiramente o problema en cuestión. Desafortunadamente, na realidade, estes documentos adoitan acabar almacenados nalgún lugar de Confluence, compartidos co equipo ao comezo dun proxecto, e despois case nunca se actualizan de novo. Non me malinterpretes: estes documentos   importantes. son Extraer coñecemento de expertos no dominio debería ser unha prioridade para calquera equipo de enxeñaría. Pero as especificacións evolucionan, os prazos estresan a todos, e eses documentos orixinais convértense lenta pero seguramente nunha base desactualizada. O coñecemento de requisitos cambiantes, casos límite e pivotes de proxectos acaba vivindo no código — ou peor! — nas cabezas de programadores senior. Para abordar isto, deixamos de escribir especificacións en arquivos Word aleatorios ou páxinas de Confluence destinadas a ser esquecidas e movemolas o máis preto posible da liña de fronte:  o repositorio de código. Comezamos a almacenalas como arquivos Markdown (.md) dentro do repo, xeralmente nunha carpeta docs/. En grandes contornos de microservizos, estes documentos poden incluso xustificar un repositorio dedicado enlazado como un submódulo de Git. Os submódulos son a miúdo pasados por alto, pero son unha forma poderosa de manter organizados os ecosistemas multi-repo. Para máis información sobre submódulos, recomendo encarecidamente esta entrada de blog —  . enlace 2. README – A Porta de Entrada para Humanos Se as especificacións do cliente son a enciclopedia, o README é a porta de entrada. E aínda así, é unha das pezas de documentación máis pasadas por alto nos proxectos de software. Irónicamente, case todas as plataformas de control de versión — GitHub, GitLab, Bitbucket — renderizan automaticamente o README directamente na páxina principal do proxecto. É a primeira cousa que calquera programador ve ao chegar ao repositorio. A pesar diso, os README adoitan estar sorprendentemente baleiros, dolorosamente desactualizados ou cheos do temido "TODO: escribir documentación máis tarde", que, por suposto, nunca ocorre. Un bo README non é opcional. É o único documento con máis probabilidades de ser lido porque require  . E como está na raíz do repo, os programadores son máis propensos a actualizalo mentres traballan no código. É documentación que vive no camiño de menor resistencia. cero clics Un README ben escrito debería responder ás preguntas máis importantes que un programador ten nos primeiros minutos de atoparse cun proxecto: 
 
 
 
 
 
 
  unha declaración concisa de propósito e contexto — sen fume de marketing. Que fai este servizo/proxecto/compoñente? —  instrucións de execución, variables de contorno, configuración de dependencias e calquera comando específico do proxecto. Como o executo localmente? —  probas unitarias, probas de integración, configuración de datos de proba e calquera ferramenta relacionada coas probas. Como o testo? —  unha breve explicación da disposición dos directorios, módulos clave e onde atopar as partes importantes do código. Como está estruturado o proxecto? —  Scripts de despregamento, notas de CI/CD, permisos requiridos ou matices da plataforma. Como o implanto?  enlaces a documentos xerados, notas de arquitectura, referencias de API e documentos de deseño centralizados. Onde podo ler máis? — O README é a porta de entrada ao proxecto. Establece expectativas, reduce o tempo de incorporación e ofrece a cada enxeñeiro — novo ou experimentado — un punto de orientación claro. Cando se mantén correctamente, convértese no documento único máis valioso de todo o repositorio. 3. JavaDocs – Documentos que o Compilador Molesta en Manter JavaDocs — xeralmente invisibles, a miúdo esquecidos, pero absolutamente esenciais cando algo falla. Na práctica, documentar proxectos Java adoita caer en dous extremos: ou  , ou   porque "o código se auto-documenta". A verdade, como sempre, está nalgún lugar no medio. sobrecomentar cada liña trivial ningún comentario Para o noso proxecto, tomamos unha decisión consciente de documentar  . Iso significou: só o que era realmente necesario 
 
 
 
 
 usar   para que os termos do dominio coincidisen exactamente co que estaba nas especificacións de negocio linguaxe ubicua explicar o   de decisións non obvias, non o   xa revela o código porqué que documentar clases do dominio principal, interfaces e fluxos de traballo complexos evitar muros de comentarios que simplemente repiten o nome do método de forma verbosa JavaDocs, cando se usan correctamente, serven como a documentación a nivel micro que aclara a intención sen saturar o código. E a diferenza das páxinas de Confluence, JavaDocs veñen cunha vantaxe incorporada: 
 
 O compilador realmente queixa cando se desincronizan. Se renomeas un parámetro pero esqueces a etiqueta JavaDoc, a compilación lémbrate. Se eliminas un método pero deixas referencias de comentarios obsoletas, a IDE acéndese como unha árbore de Nadal. Esta fricción suave é exactamente por que os JavaDocs tenden a permanecer máis precisos que outras formas de documentación — son molestos de descoidar. Para manter todo centralizado e evitar "illas de documentación", tamén usamos  . Doxygen Doxygen é unha ferramenta xeradora de documentación amplamente utilizada no desenvolvemento de software. Aínda que se usa principalmente na comunidade C++, usámola para agregar os JavaDocs nunha referencia consistente e navegable — unha páxina HTML. Ten unha serie de características que JavaDoc non ofrece, por exemplo, os diagramas de clases para as xerarquías e o contexto de cooperación, máis páxinas de resumo, e moitos máis. Isto deunos unha vista limpa e unificada de todo o codebase sen depender de pistas dispersas da IDE. 4. Código Limpo – A Documentación que Non Necesitas Manter Finalmente, a forma de documentación máis subestimada é tamén a que os programadores respectan menos ata que realmente a necesitan:  código limpo. Os comentarios envellecen. As especificacións desvíanse. Os README ignóranse. Os JavaDocs poden volverse obsoletos. Pero o código ben escrito — claro, intencional e expresivo —   documentación. é Como dixo famosamente Uncle Bob,  "o código limpo léese como prosa ben escrita." E na práctica, iso significa: 
 
 
 
 
 
 
 clases e métodos con nomes que revelan o seu propósito funcións que fan unha soa cousa e fanna ben terminoloxía do dominio usada consistentemente en todas partes ningunha intelixencia por si mesma ningunha "comportamento sorpresa" oculto dentro de efectos secundarios ningunha abstracción innecesariamente profunda que requira un PhD para entender O código limpo é o único artefacto garantido para sobrevivir a refactorizacións, sprints, rotación de persoal e caos organizativo. Sempre está en sincronía co comportamento do sistema porque —   o comportamento do sistema. é Unha regra sinxela xurdiu para nós co tempo:  Se necesitas un parágrafo de comentarios para explicar un método, o problema real é o método. Cando o código é expresivo, todo o demais faise máis doado → os JavaDocs fanse máis lixeiros e enfocados → o README encóllese porque a incorporación se fai obvia → as especificacións fanse máis claras porque o modelo de dominio reflicte o vocabulario de negocio. O código limpo non elimina a necesidade de documentación;  a. âncora Asegura que todas as outras formas de documentación — especificacións, READMEs, JavaDocs — están a reforzar a verdade en lugar de compensar unha implementación pouco clara. Ao final, o código limpo é a documentación que non require mantemento, nin integración CI, nin ferramentas. É a explicación máis honesta e fiable do que o sistema realmente fai. Xuntándoo Todo — Unha Pipeline de Documentación Viva Despois de refinar como escribiamos a documentación, o último paso foi asegurar que non só se creara — senón que se entregase continuamente e sempre estivese accesible. Para iso, construímos unha pipeline de documentación que converteu as nosas especificacións, arquivos README e JavaDocs nun único portal de   unificado. documentación viva Como queriamos que os nosos documentos vivisen o máis preto posible do noso código, decidimos despregar todo a través de  , o que nos proporcionou unha solución de aloxamento sen esforzo e controlada por versión directamente ligada ao codebase. GitHub Pages non é particular de GitHub (GitLab, por exemplo, tamén ten GitLab Pages) — é outra característica útil dos sistemas de control de versión populares que recomendo para máis lectura —  . GitHub Pages enlace Para compilar todo nun conxunto de páxinas cohesionadas, usamos  Sphinx. Sphinx é un potente xerador de documentación escrito en Python. Toma arquivos fonte escritos en reStructuredText ou Markdown e tradúceos a varios formatos de saída, incluíndo HTML, PDF e ePub. Sphinx encargouse da estrutura, navegación e temas. Doxygen alimentou a Sphinx con JavaDocs xerados automaticamente usando o plugin  , proporcionándonos unha referencia de API totalmente navegable directamente desde o código fonte. Mentres tanto, o README raíz serviu como punto de entrada inmediato para os programadores que exploraban o repositorio, enlazando sen problemas ao sitio de documentación xerado. Breathe Cada merge no main disparaba un traballo de CI que reconstruía os documentos, asegurando que o portal reflectise os últimos cambios de código, actualizacións de API e decisións de deseño. Nada vivía illado. Nada requiría sincronización manual. E crucialmente — nada estaba a máis dun clic. Isto converteu a nosa documentación dun artefacto estático nun ecosistema continuamente actualizado que os programadores realmente usaban, porque estaba integrado directamente no seu fluxo de traballo diario e vivía xunto ao código. Conclusión — A Documentación é a Nosa Responsabilidade, Non a Nosa Carga Ao final do día, escribir documentación non é opcional. É parte do noso traballo como profesionais da enxeñaría. Os futuros compañeiros de equipo dependen dela. A incorporación depende dela. O mantemento, a fiabilidade e mesmo a claridade arquitectónica dependen dela. Pero aceptar esa responsabilidade non significa que a documentación teña que ser dolorosa. Ao manter os documentos preto do código, automatizar o que se poida automatizar e confiar en ferramentas intelixentes como Markdown, JavaDocs, Doxygen e Sphinx, eliminamos a fricción que normalmente mata os esforzos de documentación. Convertimos algo que tradicionalmente se sente como unha tarefa nunha extensión natural do desenvolvemento cotián. E cando emparellamos iso con código limpo, bos READMEs e especificacións ricas en dominio, todo o ecosistema convértese en autosostible. A documentación non precisa ser perfecta — só precisa ser accesible, precisa e viva. Cando construímos sistemas que animan aos programadores a actualizar documentos tan facilmente como escriben código, todos se benefician: o equipo, o produto e, o máis importante, a pobre alma que herda o proxecto seis meses despois. A boa documentación non nos fai menos preguiceiros. Simplemente fai que ser preguiceiro sexa compatible coa construción de software excelente.

The is an opinion piece based on the author’s POV and does not necessarily reflect the views of HackerNoon.

Read My Stories

Este audio está producido na lingua orixinal da historia!

Se a túa documentación tarda dous clics en abrirse, parabéns: xa está desactualizada

About Author

COMENTARIOS

Etiquetas colgantes

ESTE ARTIGO FOI PRESENTADO EN

Related Stories

Coñece R Systems: HackerNoon empresa da semana

HackerNoon Decoded 2024: Celebrating Our Management Community!

HackerNoon Decoded 2024: Celebrating Our Science Community!

HackerNoon Decoded 2024: Celebrating Our Programming Community!

Coñece R Systems: HackerNoon empresa da semana

HackerNoon Decoded 2024: Celebrating Our Management Community!

HackerNoon Decoded 2024: Celebrating Our Science Community!

HackerNoon Decoded 2024: Celebrating Our Programming Community!

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps