Gjatë viteve, kam punuar në të gjitha llojet e projekteve – të mëdha, të vogla, kaotike, të mbinxhiruara, “të përkohshme”, të supozuara mirë të strukturuara, dhe gjithçka në mes. The documentation is always missing, outdated, or buried in some forgotten corner of Confluence guarded by a 2019 timestamp. Çdo projekt për të pasur dokumentacion. pretendimet Çdo ekip Ata do ta mbajnë të përditësuar. premtimeve Dhe çdo zhvillues me besim thotë, “Mos u shqetësoni, unë do ta shkruaj më vonë”, e cila, siç e dimë të gjithë, është dokumentacioni ekuivalent me të thënë Çeku është në postë”. Pas shikimit të këtij cikli të përsëritur më shumë herë se sa do të doja të pranoja, kuptova diçka të thjeshtë, por brutalisht të vërtetë: 
 
 Dokumentacioni mbijeton vetëm nëse jeton sa më afër kodit të jetë e mundur – sepse zhvilluesit (duke përfshirë edhe veten time) janë krijesa dembelë. Documentation only survives if it lives as close to the code as possible—because developers (myself included) are lazy creatures. Dhe nga kjo, erdhi një realizim tjetër - problemi kryesor me dokumentacionin e vjetëruar është fakti se shumica e ekipeve nuk e konsiderojnë atë si pjesë të ciklit kryesor të zhvillimit, duke e lënë atë për më vonë ose duke bërë me një çift të specifikacioneve para-dev që ata tashmë kishin diku në Confluence. Për të shkruar dokumentacion kuptimplotë, le të diskutojmë së pari se çfarë lloj dokumentacioni ekziston për një komponent softueri: Ways to Document Code (That Developers Might Actually Use) Mënyra për të dokumentuar kodin (që zhvilluesit mund të përdorin në të vërtetë) Pasi të pranoni se dokumentacioni duhet të jetojë afër kodit, pyetja tjetër është për ta strukturuar atë. Si Në praktikë, kam gjetur se dokumentacioni i mirë nuk është një artefakt i vetëm - është një ekosistem i vogël i shtresave, secila duke shërbyer një qëllim dhe audiencë të ndryshme. Për atë projekt që kam përmendur (shkruar në Java + Spring Boot), ne kemi identifikuar katër lloje kryesore të dokumenteve: 1. Client Specs Në mënyrë ideale, ato janë të pasura me gjuhë të gjithanshme dhe ofrojnë përshkrime kode-agnostike të rasteve të biznesit - me fjalë të tjera, gjithçka që një inxhinier ka nevojë për të kuptuar me të vërtetë problemin në dorë. Për fat të keq, në realitet, këto dokumente shpesh përfundojnë të ruhen diku në Confluence, të ndara me ekipin në fillim të një projekti, dhe pastaj pothuajse kurrë nuk përditësohen përsëri. Mos më merrni gabim: këto dokumente të rëndësishme. janë Ekstraktimi i njohurive nga ekspertët e domain-it duhet të jetë një prioritet i lartë për çdo ekip inxhinierik.Por specifikimet evoluojnë, afatet e afate stresojnë të gjithë, dhe ato dokumente origjinale ngadalë por me siguri bëhen një themel i vjetëruar. Njohja e kërkesave të ndryshueshme, rastet e krahut dhe pivotet e projektit përfundon duke jetuar në kod - ose më keq! - në kokat e zhvilluesve të lartë. Për të adresuar këtë, ne kemi ndaluar shkrimin e specifikimeve në skedarët e rastit Word ose faqet e Konfluencës të destinuara për t'u harruar dhe i kemi lëvizur ato sa më afër vijës së parë të jetë e mundur: the code repository. Ne filluam t'i ruajmë ato si skedarë Markdown (.md) brenda repo, zakonisht në një dosje / dosje. Në mjediset e mëdha të microservices, këto dokumente mund të justifikojnë edhe një repository të dedikuar të lidhur si një submodul Git. Për lexim të mëtejshëm në submodules, unë rekomandoj këtë blog post - . Lidhja 2. README – The Front Door for Humans Nëse specifikimet e klientit janë enciklopedi, README është dera e parë. Ironikisht, pothuajse çdo platformë e kontrollit të versionit - GitHub, GitLab, Bitbucket - automatikisht rendit README në faqen kryesore të projektit. Kjo është gjëja e parë që çdo zhvillues e sheh kur ulet në depo. Një README i mirë nuk është opsional. është dokumenti i vetëm që ka më shumë gjasa të lexohet sepse kërkon Dhe për shkak se qëndron në rrënjë të repo, zhvilluesit kanë më shumë gjasa ta përditësojnë atë ndërsa punojnë në kod. zero clicks Një README i shkruar mirë duhet të përgjigjet në pyetjet më të rëndësishme që një zhvillues ka brenda minutave të para të takimit me një projekt: 
 
 
 
 
 
 
 Çfarë bën ky shërbim / projekt / komponent? - një qëllim të shkurtër dhe një deklaratë kontekstuale - asnjë rrjedhje e marketingut. Si ta drejtoj atë në vend? - udhëzime të kohës së drejtimit, variablat e mjedisit, konfigurimi i varësisë dhe çdo komandë specifike të projektit. Si mund ta testoj atë? - testet e njësive, testet e integrimit, konfigurimi i të dhënave të testimit dhe çdo mjet i lidhur me testin. Si është e strukturuar projekti? - një shpjegim i shkurtër i vendosjes së directory, modulet kyçe, dhe ku për të gjetur pjesët e rëndësishme të kodit. Si ta vendos atë? skripte të vendosjes, shënime CI / CD, lejet e kërkuara ose nuancat e platformës. Ku mund të lexoj më tej? - Lidhjet me dokumentet e gjeneruara, shënimet e arkitekturës, referencat e API-ve dhe dokumentet e projektimit të centralizuar. README është porta e hyrjes në projekt. Ai përcakton pritjet, zvogëlon kohën e hyrjes dhe i jep çdo inxhinieri – të ri ose me përvojë – një pikë orientimi të qartë. 3. JavaDocs – Docs That The Compiler Annoys You Into Maintaining JavaDocs - zakonisht të padukshme, shpesh të harruara, por absolutisht thelbësore kur diçka thyhet. Në praktikë, dokumentimi i projekteve Java shpesh bie në dy ekstreme: ose ose Sepse “kodi është vetë-dokumentues”.E vërteta, si gjithmonë, është diku në mes. over-commenting every trivial line no comments at all Për projektin tonë, kemi marrë një vendim të ndërgjegjshëm për të dokumentuar Kjo do të thotë: only what was genuinely necessary 
 
 
 
 
 duke përdorur gjuhë të përhapur në mënyrë që termat e domain të përputhen saktësisht me atë që ishte në specifikimet e biznesit duke shpjeguar pse pas vendimeve jo të dukshme, jo atë që tashmë zbulon kodi Dokumentimi i klasave të domeneve thelbësore, ndërfaqeve dhe rrjedhave të punës komplekse shmangni muret e komentit që thjesht përsërisin emrin e metodës në formë verbose JavaDocs, kur përdoret siç duhet, shërben si dokumentacioni mikro-nivel që sqaron qëllimin pa ngatërruar kodin. 
 
 Kompilatori në fakt ankohet kur dalin jashtë sinkronizimit. Nëse riemërtoni një parametër, por harroni etiketën JavaDoc, ndërtimi ju kujton. Nëse fshini një metodë, por lini referenca të palëvizshme të komentit, IDE ndriçon si një pemë e Krishtlindjeve. Kjo fërkim i butë është pikërisht arsyeja pse JavaDocs kanë tendencë të mbeten më të sakta se format e tjera të dokumentacionit - ata janë të bezdisshëm për t'u neglizhuar. Për të mbajtur gjithçka të centralizuar dhe për të shmangur “ishujt e dokumentacionit”, ne gjithashtu përdorim . Doxygen Doxygen është një mjet i përdorur gjerësisht në zhvillimin e softuerit. Ndërsa përdoret kryesisht në komunitetin C++, ne e përdorim atë për të grumbulluar JavaDocs në një referencë të qëndrueshme, të shfletueshme - një faqe HTML. Ajo ka një numër karakteristikash që JavaDoc nuk ofron, p.sh., diagramet e klasave për hierarkitë dhe kontekstin e bashkëpunimit, më shumë faqe përmbledhjeje, dhe shumë më tepër. Kjo na dha një pamje të pastër, të unifikuar të gjithë bazës së kodit pa u mbështetur në këshilla të shpërndara IDE. 4. Clean Code – The Documentation You Don’t Need to Maintain Së fundi, forma më e nënvlerësuar e dokumentacionit është gjithashtu ajo që zhvilluesit e respektojnë më pak derisa ata me të vërtetë kanë nevojë për të: clean code. Komentet moshë. Specs drift. READMEs të injoruar. JavaDocs mund të bëhet i paqëndrueshëm. Por kodi i shkruar mirë – i qartë, i qëllimshëm dhe ekspresiv – dokumentacionit të është Siç thoshte xhaxhai Bob, “Clean code reads like well-written prose.” Në praktikë, kjo do të thotë: 
 
 
 
 
 
 
 Klasat dhe metodat me emra që zbulojnë qëllimin e tyre Funksionet që bëjnë një gjë dhe e bëjnë mirë Terminologjia e domeneve përdoret në mënyrë konsistente gjatë gjithë kohës Asnjë zgjuarsi për hir të vetes Nuk ka “sjellje befasuese” të fshehura brenda efekteve anësore asnjë abstraksione të panevojshme të thella që kërkojnë një doktoraturë për të kuptuar Kodi i pastër është një artifakt i garantuar për të mbijetuar refaktorët, sprintet, qarkullimi i stafit dhe kaosin organizativ. sjelljen e sistemit. is Një rregull i thjeshtë u shfaq për ne me kalimin e kohës: If you need a paragraph of comments to explain a method, the real problem is the method. Kur kodi është ekspresiv, gjithçka tjetër bëhet më e lehtë → JavaDocs bëhen më të lehta dhe më të fokusuara → README zvogëlohet sepse futja bëhet e dukshme → specifikimet bëhen më të qarta sepse modeli i domain pasqyron fjalorin e biznesit. Kodi i pastër nuk e eliminon nevojën për dokumentacion; ai të Ankarasë Ajo siguron që të gjitha format e tjera të dokumentacionit - specs, READMEs, JavaDocs - janë përforcimi i së vërtetës në vend që të kompensojë për zbatimin e paqartë. Në fund të fundit, kodi i pastër është dokumentacioni që nuk kërkon mirëmbajtje, asnjë integrim CI dhe asnjë mjet. Bringing It All Together — A Living Documentation Pipeline Bringing It All Together – Një tubacion i gjallë i dokumentacionit Pas përmirësimit të mënyrës se si kemi shkruar dokumentacionin, hapi i fundit ishte të siguroheshim që ai të mos ishte vetëm i krijuar – por i dorëzuar vazhdimisht dhe gjithmonë i arritshëm. . living documentation portal Meqenëse ne donim që dosjet tona të jetonin sa më afër kodit tonë, ne vendosëm të vendosim gjithçka përmes Github Pages nuk është e veçantë për Github (GitLab, për shembull, gjithashtu ka faqet GitLab) - kjo është një tjetër tipar i pastër i sistemeve popullore të kontrollit të versionit unë rekomandoj për lexim të mëtejshëm - . GitHub Pages Lidhja Për të mbledhur gjithçka në një sërë faqeve kohezive, ne kemi përdorur Sphinx. Sphinx është një gjenerator i fuqishëm i dokumentacionit i shkruar në Python. Ajo merr skedarët burim të shkruar në reStructuredText ose Markdown dhe i përkthen ato në formate të ndryshme të prodhimit, duke përfshirë HTML, PDF dhe ePub. Sphinx menaxhoi strukturën, navigimin dhe temën. Doxygen ushqeu Sphinx me JavaDocs të gjeneruara automatikisht duke përdorur plugin, duke na dhënë një referencë të plotë të shfletueshme të API direkt nga kodi burimor. ndërkohë, README rrënjë shërbeu si pika e hyrjes së menjëhershme për zhvilluesit që eksplorojnë depo, duke lidhur pa probleme në faqen e dokumentacionit të gjeneruar. frymë Çdo përzierje në kryesore shkaktoi një punë CI që rindërtoi dokumentet, duke siguruar që portali pasqyronte ndryshimet e fundit të kodit, përditësimet e API-ve dhe vendimet e projektimit. Asgjë nuk jetonte në izolim. Asgjë nuk kërkonte sinkronizim manual. Kjo e shndërroi dokumentacionin tonë nga një artefakt statik në një ekosistem të përditësuar vazhdimisht që zhvilluesit në fakt e përdorin, sepse ajo u integrua direkt në rrjedhën e tyre të përditshme të punës dhe jetonte së bashku me kodin. Conclusion — Documentation Is Our Responsibility, Not Our Burden Dokumentimi është përgjegjësia jonë, jo barrë jonë Në fund të ditës, shkrimi i dokumentacionit nuk është opsional. Kjo është pjesë e punës sonë si profesionistë inxhinierë. Bashkëpunëtorët e ardhshëm të ekipit varen nga ajo. Onboarding varet nga ajo. Mirëmbajtja, besueshmëria dhe madje edhe qartësia arkitektonike varen nga ajo. por pranimi i kësaj përgjegjësie nuk do të thotë se dokumentacioni duhet të jetë i dhimbshëm. Duke mbajtur dokumente afër kodit, duke automatizuar gjithçka që mund të automatizohet, dhe duke u mbështetur në mjete të zgjuara si Markdown, JavaDocs, Doxygen dhe Sphinx, ne heqim frikën që normalisht vret përpjekjet e dokumentimit.Ne e shndërrojmë diçka që tradicionalisht duket si një detyrë në një zgjatje natyrore të zhvillimit të përditshëm. Kur ne ndërtojmë sisteme që inkurajojnë zhvilluesit të përditësojnë dokumente aq lehtë sa ata shkruajnë kod, të gjithë përfitojnë: ekipi, produkti dhe më e rëndësishmja, shpirti i varfër që trashëgon projektin gjashtë muaj më vonë. Dokumentacioni i mirë nuk na bën më pak dembelë, thjesht e bën të qenit dembelë në përputhje me ndërtimin e softuerëve të mëdhenj.

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

Every

Front

Read My Stories

Kjo audio është prodhuar në gjuhën origjinale të tregimit!

Nëse dokumentacioni juaj merr dy klikime për të hapur, kongrats - ajo është tashmë e vjetëruar

About Author

KOMENTE

VARUR TAGS

KY ARTIKU U PARAQIT NË

Related Stories

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps