
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 Al llarg dels anys, he treballat en tot tipus de projectes: grans, petits, caòtics, sobre-enginyats, "temporals", aparentment ben estructurats i tot el que hi ha al mig. I tanmateix, un patró ha estat hilarantment constant: La documentació sempre falta, està desfasada o està enterrada en algun racó oblidat de Confluence, protegit per una marca de temps del 2019. Cada projecte *pretén* tenir documentació. Cada equip *promet* que la mantindrà actualitzada. I cada desenvolupador diu amb seguretat: "No et preocupis, ja l'escriuré més tard", que, com tots sabem, és l'equivalent en documentació de dir * "el xec està al correu".* Després de veure aquest cicle repetir-se més vegades del que m'agradaria admetre, em vaig adonar d'una cosa senzilla però brutalment vera: 
 
 La documentació només sobreviu si viu el més a prop possible del codi, perquè els desenvolupadors (inclòs jo mateix) som criatures gandules. I d'això, va sorgir una altra constatació: el problema principal de la documentació desfasada és el fet que la majoria dels equips no la consideren part del cicle de desenvolupament principal, deixant-la per més tard o conformant-se amb un parell d'especificacions pre-desenvolupament que ja tenien en algun lloc de Confluence. Per escriure documentació significativa, primer discutim quin tipus de documentació existeix per a un component de programari: Maneres de documentar el codi (que els desenvolupadors podrien utilitzar realment) Un cop accepteu que la documentació ha de viure a prop del codi, la següent pregunta és *com* estructurar-la. A la pràctica, he trobat que una bona documentació no és un sol artefacte; és un petit ecosistema de capes, cadascuna amb un propòsit i una audiència diferents. Per a aquell projecte que vaig esmentar (escrit en Java + Spring Boot), vam identificar quatre tipus principals de documents: 1. Especificacions del client Aquests són documents convencionals, normalment compilats per un expert en domini. Idealment, són rics en llenguatge বললেন i proporcionen descripcions de casos de negoci agnòstiques al codi; en altres paraules, tot el que un enginyer necessita per entendre realment el problema en qüestió. Malauradament, en realitat, aquests documents sovint acaben emmagatzemats en algun lloc de Confluence, compartits amb l'equip al principi d'un projecte, i després gairebé mai més actualitzats. No m'entenguis malament: aquests documents *són* importants. Extreure coneixement d'experts en domini hauria de ser una prioritat per a qualsevol equip d'enginyeria. Però les especificacions evolucionen, els terminis límit estressen tothom, i aquells documents originals es converteixen lentament però de manera segura en una base desfasada. El coneixement de canvis de requisits, casos límit i pivots de projecte acaba vivint al codi, o pitjor! - al cap dels desenvolupadors sènior. Per abordar això, vam deixar d'escriure especificacions en arxius de Word aleatoris o pàgines de Confluence destinades a ser oblidades i les vam apropar el màxim possible a la primera línia:  el repositori de codi. Vam començar a emmagatzemar-les com a fitxers Markdown (.md) dins del repo, normalment en una carpeta docs/. En entorns de microserveis grans, aquests documents poden fins i tot justificar un repositori dedicat enllaçat com a submodule de Git. Els submodules sovint s'ignoren, però són una manera potent de mantenir organitzats els ecosistemes de múltiples repos. Per a més lectures sobre submodules, recomano encaridament aquesta publicació de bloc -  . enllaç 2. README – La porta d'entrada per a humans Si les especificacions del client són l'enciclopèdia, el README és la porta d'entrada. I tanmateix, és una de les peces de documentació més ignorades en els projectes de programari. Irònicament, gairebé totes les plataformes de control de versions – GitHub, GitLab, Bitbucket – renderitzen automàticament el README directament a la pàgina principal del projecte. És la primera cosa que qualsevol desenvolupador veu quan arriba al repositori. Malgrat això, els README són sovint sorprenentment buits, dolorosament desfasats o plens del maleït "TODO: escriure documentació més tard", que, per descomptat, mai succeeix. Un bon README no és opcional. És l'únic document que és més probable que es llegeixi, perquè requereix  . I com que es troba a la arrel del repo, els desenvolupadors són més propensos a actualitzar-lo mentre treballen en el codi. És documentació que viu pel camí de menor resistència. zero clics Un README ben escrit hauria de respondre a les preguntes més importants que un desenvolupador té en els primers minuts de trobar-se amb un projecte: 
 
 
 
 
 
 
  una declaració concisa de propòsit i context, sense floritures de màrqueting. Què fa aquest servei/projecte/component? -  instruccions d'execució, variables d'entorn, configuració de dependències i qualsevol comandament específic del projecte. Com el faig córrer localment? -  proves unitàries, proves d'integració, configuració de dades de prova i qualsevol eina relacionada amb les proves. Com el faig provar? -  una breu explicació de la disposició del directori, els mòduls clau i on trobar les parts importants del codi. Com està estructurat el projecte? -  Scripts de desplegament, notes de CI/CD, permisos requerits o nuances de plataforma. Com el faig desplegar?  enllaços a documentació generada, notes d'arquitectura, referències d'API i documents de disseny centralitzats. On puc llegir més? - El README és la porta d'entrada al projecte. Estableix expectatives, redueix el temps d'incorporació i proporciona a cada enginyer, nou o experimentat, un punt d'orientació clar. Quan es manté adequadament, es converteix en el document individual més valuós de tot el repositori. 3. JavaDocs – Documents que el compilador us molesta a mantenir JavaDocs – normalment invisibles, sovint oblidats, però absolutament essencials quan alguna cosa es trenca. A la pràctica, documentar projectes Java sovint cau en dos extrems: o bé  , o bé   perquè "el codi s'auto-documenta". La veritat, com sempre, es troba enmig. sobre-comentar cada línia trivial cap comentari Per al nostre projecte, vam prendre una decisió conscient de documentar  . Això significava: només allò que era genuïnament necessari 
 
 
 
 
 utilitzar   de manera que els termes del domini coincidissin exactament amb el que hi havia a les especificacions de negoci llenguatge বললেন explicar el *per què* darrere de decisions no òbvies, no el *què* que ja revela el codi documentar classes del domini central, interfícies i fluxos de treball complexos evitar murs de comentaris que simplement repeteixen el nom del mètode de forma verbal JavaDocs, quan s'utilitza correctament, serveixen com a documentació a nivell micro que aclareix la intenció sense omplir el codi. I a diferència de les pàgines de Confluence, JavaDocs tenen un avantatge integrat: 
 
 El compilador es queixa realment quan es desincronitzen. Si canvieu el nom d'un paràmetre però oblideu l'etiqueta JavaDoc, la compilació us ho recorda. Si elimineu un mètode però deixeu referències de comentaris obsolets, l'IDE s'il·lumina com un arbre de Nadal. Aquesta fricció suau és exactament per què els JavaDocs tendeixen a romandre més precisos que altres formes de documentació: són molestos de descuidar. Per mantenir-ho tot centralitzat i evitar "illes de documentació", també vam utilitzar  . Doxygen Doxygen és una eina de generació de documentació àmpliament utilitzada en el desenvolupament de programari. Tot i que s'utilitza principalment a la comunitat C++, la vam utilitzar per agregar els JavaDocs en una referència coherent i navegable, una pàgina HTML. Té una sèrie de característiques que JavaDoc no ofereix, per exemple, els diagrames de classes per a les jerarquies i el context de cooperació, més pàgines de resum, i moltes més. Això ens va donar una visió neta i unificada de tot el codi sense dependre de suggeriments dispersos de l'IDE. 4. Codi net – La documentació que no necessites mantenir Finalment, la forma de documentació més infravalorada és també la que els desenvolupadors respecten menys fins que realment la necessiten:  el codi net. Els comentaris envellixen. Les especificacions s'estressen. Els README s'ignoren. Els JavaDocs poden quedar obsolets. Però el codi ben escrit –clar, intencional i expressiu– *és* documentació. Com va dir cèlebrement l'Oncle Bob,  "El codi net es llegeix com una prosa ben escrita." I a la pràctica, això significa: 
 
 
 
 
 
 
 classes i mètodes amb noms que revelen el seu propòsit funcions que fan una cosa i la fan bé terminologia del domini utilitzada consistentment al llarg del text cap astúcia per si mateixa cap "comportament sorpresa" amagat dins d'efectes secundaris cap abstracció innecessàriament profunda que requereixi un doctorat per entendre-la El codi net és l'únic artefacte garantit per sobreviure a refactors, sprints, rotació de personal i caos organitzatiu. Sempre està sincronitzat amb el comportament del sistema perquè, de fet,   el comportament del sistema. és Una regla senzilla va sorgir per a nosaltres amb el temps:  Si necessites un paràgraf de comentaris per explicar un mètode, el veritable problema és el mètode. Quan el codi és expressiu, tot el que és altre es torna més fàcil → els JavaDocs es tornen més lleugers i més enfocats → el README s'encongeix perquè la incorporació es torna òbvia → les especificacions es tornen més clares perquè el model de domini reflecteix el vocabulari de negoci. El codi net no elimina la necessitat de documentació; la *ancora*.  Garanteix que totes les altres formes de documentació – especificacions, READMEs, JavaDocs – reforcen la veritat en lloc de compensar una implementació poc clara. Al final, el codi net és la documentació que no requereix manteniment, ni integració de CI, ni eines. És la explicació més honesta i fiable del que fa realment el sistema. Unint-ho tot: una pipeline de documentació viva Després de refinar com escrivíem la documentació, el pas final va ser assegurar-nos que no només es creava, sinó que es lliurava contínuament i sempre era accessible. Per a això, vam construir una pipeline de documentació que va convertir les nostres especificacions, fitxers README i JavaDocs en un portal de documentació viva, únic i unificat. Com que volíem que els nostres documents visquessin el més a prop possible del nostre codi, vam decidir desplegar-ho tot a través de  , que ens va proporcionar una solució d'allotjament sense esforç i controlada per versions directament lligada al codi base. GitHub Pages no és exclusiu de Github (GitLab, per exemple, també té GitLab Pages); és una altra característica interessant dels sistemes de control de versions populars que recomano per a més lectures -  . GitHub Pages enllaç Per compilar-ho tot en un conjunt de pàgines cohesionades, vam utilitzar  Sphinx. Sphinx és un potent generador de documentació escrit en Python. Pren fitxers font escrits en reStructuredText o Markdown i els tradueix a diversos formats de sortida, incloent HTML, PDF i ePub. Sphinx es va encarregar de l'estructura, la navegació i la temàtica. Doxygen va alimentar Sphinx amb JavaDocs auto-generats utilitzant el plugin  , donant-nos una referència d'API completament navegable directament des del codi font. Mentrestant, el README arrel va servir com a punt d'entrada immediat per als desenvolupadors que exploraven el repositori, enllaçant perfectament al lloc de documentació generat. Breathe Cada merge a main activava un treball de CI que reconstruïa els documents, assegurant que el portal reflectís els últims canvis de codi, actualitzacions d'API i decisions de disseny. Res no vivia aïllat. Res no requeria sincronització manual. I crucialment, res no estava a més d'un clic de distància. Això va convertir la nostra documentació d'un artefacte estàtic a un ecosistema contínuament actualitzat que els desenvolupadors realment utilitzaven, perquè estava integrat directament en el seu flux de treball diari i vivia just al costat del codi. Conclusió: La documentació és la nostra responsabilitat, no la nostra càrrega Al final, escriure documentació no és opcional. És part de la nostra feina com a professionals de l'enginyeria. Els futurs companys hi depenen. La incorporació hi depèn. El manteniment, la fiabilitat i fins i tot la claredat arquitectònica hi depenen. Però acceptar aquesta responsabilitat no vol dir que la documentació hagi de ser dolorosa. Mantenint els documents a prop del codi, automatitzant el que es pot automatitzar i confiant en eines intel·ligents com Markdown, JavaDocs, Doxygen i Sphinx, eliminem la fricció que normalment mata els esforços de documentació. Convertim alguna cosa que tradicionalment se sent com una tasca en una extensió natural del desenvolupament diari. I quan ho combinem amb codi net, bons READMEs i especificacions riques en domini, tot l'ecosistema es torna autosuficient. La documentació no ha de ser perfecta; només ha de ser accessible, precisa i viva. Quan construïm sistemes que animen els desenvolupadors a actualitzar documents tan fàcilment com escriuen codi, tothom en surt beneficiat: l'equip, el producte i, sobretot, la pobra ànima que hereta el projecte sis mesos després. La bona documentació no ens fa menys ganduls. Simplement fa que ser gandul sigui compatible amb la construcció de programari excel·lent.

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

Read My Stories

Aquest àudio és produït a l'idioma original de la història!

Si la vostra documentació triga dos clics a obrir-se, felicitats: ja està obsoleta

About Author

COMENTARIS

Etiquetes penjant

AQUEST ARTICLE VA SER PRESENTAT A

Related Stories

Generar líders de qualitat ASAP: HackerNoon's Content-Relevant Niche Ads FTW

How AWS, Bosch & Brave Reach 4M+ Tech Pros on HackerNoon

How to Turn Year-End Reflections into Q1 Content Gold

Startups of The Year: Meet the Business Industry

Generar líders de qualitat ASAP: HackerNoon's Content-Relevant Niche Ads FTW

How AWS, Bosch & Brave Reach 4M+ Tech Pros on HackerNoon

How to Turn Year-End Reflections into Q1 Content Gold

Startups of The Year: Meet the Business Industry

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps