Per metus dirbau įvairiuose projektuose – dideliuose, mažuose, chaotiškuose, pernelyg inžineriniuose, „laikinuose“, tariamai gerai struktūrizuotuose, ir visur tarp jų. The documentation is always missing, outdated, or buried in some forgotten corner of Confluence guarded by a 2019 timestamp. Kiekvienas projektas Norėdami turėti dokumentus. pretenzijos Every team  Jie išlaikys jį atnaujintą. Pažadėjimai Ir kiekvienas kūrėjas pasitikėdamas sako: „Nesijaudinkite, aš tai parašysiu vėliau“, o tai, kaip mes visi žinome, yra dokumentacija, lygiavertė sakant: „Šekas yra pašto dėžutėje“. Žiūrėdamas, kaip šis ciklas kartojasi daugiau kartų, nei norėčiau pripažinti, supratau kažką paprasto, bet žiauriai tikro: 
 
 Dokumentacija išlieka tik tuo atveju, jei ji gyvena kuo arčiau kodo, nes kūrėjai (įskaitant mane) yra tingūs tvariniai. Documentation only survives if it lives as close to the code as possible—because developers (myself included) are lazy creatures. Ir iš to atsirado dar vienas supratimas - pagrindinė problema su pasenusia dokumentacija yra tai, kad dauguma komandų nelaiko jos pagrindinio vystymosi ciklo dalimi, paliekant ją vėlesniam laikui arba dėl kelių išankstinių specifikacijų, kurias jie jau turėjo kažkur „Confluence“. Norėdami parašyti prasmingą dokumentaciją, pirmiausia aptarkime, kokios rūšies dokumentacija yra programinės įrangos komponentui: Ways to Document Code (That Developers Might Actually Use) Dokumentų kodavimo būdai (Ką kūrėjai iš tikrųjų gali naudoti) Kai jūs sutinkate, kad dokumentacija turi gyventi arti kodo, kitas klausimas yra Ir jį struktūrizuoti. Kaip Praktiškai radau, kad gera dokumentacija nėra vienas artefaktas - tai maža sluoksnių ekosistema, kiekviena tarnaujanti skirtingam tikslui ir auditorijai. Tam projektui, kurį minėjau (rašytam Java + Spring Boot), mes nustatėme keturis pagrindinius dokų tipus: 1. Client Specs These are conventional documents usually compiled by a domain expert. Ideally, they’re rich with ubiquitous language and provide code-agnostic descriptions of business cases - in other words, everything an engineer needs to truly understand the problem at hand. Deja, iš tikrųjų šie dokumentai dažnai būna saugomi kažkur „Confluence“, bendrinami su komanda projekto pradžioje, o po to beveik niekada neatnaujinami. Nesupraskite manęs neteisingai: šie dokumentai Labai svarbu. yra Bet specifikacijos vystosi, terminai stumia visus, ir tie originalūs dokumentai lėtai, bet tikrai tampa pasenusiu pagrindu. Žinios apie besikeičiančius reikalavimus, kraštinius atvejus ir projekto pivotus galiausiai gyvena kodo - ar dar blogiau! - vyresniųjų kūrėjų galvose. Norėdami tai išspręsti, mes nustojome rašyti specifikacijas atsitiktiniuose "Word" failuose ar "Confluence" puslapiuose, kurie buvo skirti pamiršti, ir perkelti juos kuo arčiau pirmosios eilutės: the code repository. Mes pradėjome juos saugoti kaip „Markdown“ (.md) failus repo viduje, paprastai dokumente / aplanke. Didelėse mikropaslaugų aplinkose šie dokumentai netgi gali pateisinti specialią saugyklą, susietą kaip Git submodulis. Norėdami toliau skaityti apie submodulius, labai rekomenduoju šį tinklaraščio įrašą - . Linkų 2. README – The Front Door for Humans Jei kliento specifikacijos yra enciklopedija, README yra priekinės durys. Ironiška, kad beveik kiekviena versijų valdymo platforma - GitHub, GitLab, Bitbucket - automatiškai atveria README tiesiai pagrindiniame projekto puslapyje. Tai yra pirmas dalykas, kurį bet kuris kūrėjas mato, kai nusileidžia į saugyklą. Geras README nėra neprivalomas. tai vienas dokumentas, kuris greičiausiai bus iš tikrųjų perskaitytas, nes jis reikalauja Ir kadangi jis sėdi repo šaknyje, kūrėjai labiau linkę jį atnaujinti dirbdami su kodu. zero clicks A well-written README should answer the most important questions a developer has within the first few minutes of encountering a project: 
 
 
 
 
 
 
 Ką daro ši paslauga / projektas / komponentas? - glaustas tikslas ir kontekstas - jokių rinkodaros srautų. Kaip jį paleisti vietoje? - paleidimo laiko instrukcijos, aplinkos kintamieji, priklausomybės nustatymas ir bet kokios konkrečių projektų komandos. Kaip jį išbandyti? - vieneto testai, integracijos testai, bandymų duomenų nustatymas ir bet kokie su bandymais susiję įrankiai. Kaip projektas yra struktūrizuotas? - trumpas katalogo išdėstymo, pagrindinių modulių ir kur rasti svarbias kodo dalis paaiškinimas. Kaip jį įdiegti? įdiegimo scenarijai, CI / CD pastabos, reikalaujamos teisės arba platformos niuansai.  links to generated docs, architecture notes, API references, and centralised design documents. Where can I read further? - README yra vartai į projektą.Jis nustato lūkesčius, sumažina įkėlimo laiką ir suteikia kiekvienam inžinieriui - naujiems ar patyrusiems - aiškų orientacijos tašką. 3. JavaDocs – Docs That The Compiler Annoys You Into Maintaining JavaDocs - paprastai nematomi, dažnai pamiršti, bet absoliučiai būtini, kai kažkas sugenda. Praktiškai, dokumentuojant Java projektus dažnai patenka į du kraštutinumus: arba arba Nes „kodas yra savaime dokumentuojamas.“ Tiesa, kaip visada, yra kažkur viduryje. over-commenting every trivial line no comments at all Dėl savo projekto mes priėmėme sąmoningą sprendimą dokumentuoti Tai reiškė: only what was genuinely necessary 
 
 
 
 
 naudojant visur esančią kalbą, kad domeno terminai tiksliai atitiktų tai, kas buvo verslo specifikacijose paaiškinti, kodėl nėra akivaizdžių sprendimų, o ne tai, ką kodas jau atskleidžia pagrindinių domenų klasių, sąsajų ir sudėtingų darbo eigų dokumentavimas vengti komentarų sienų, kurios paprasčiausiai kartoja metodo pavadinimą žodžiu JavaDocs, kai naudojamas tinkamai, tarnauja kaip mikro lygio dokumentacija, kuri paaiškina ketinimą, nepažeidžiant kodo. 
 
 Kompiuteris iš tikrųjų skundžiasi, kai jie išeina iš sinchronizacijos. Jei pervadinsite parametrą, bet pamiršite „JavaDoc“ žymę, kūrimas jums primins. Jei ištrinate metodą, bet paliekate pasenusias komentarų nuorodas, IDE apšviečia kaip Kalėdų eglutė. Šis švelnus trinimas yra būtent tai, kodėl "JavaDocs" linkę likti tikslesni nei kitos dokumentų formos - jie erzina nepaisyti. Norėdami išlaikyti viską centralizuotą ir išvengti „dokumentų salų“, mes taip pat naudojome . Doxygen Doxygen yra plačiai naudojamas dokumentų generatoriaus įrankis programinės įrangos kūrimui. Nors jis daugiausia naudojamas C++ bendruomenėje, mes jį panaudojome, kad apibendrintume JavaDocs į nuoseklią, naršomą nuorodą - HTML puslapį. Tai suteikė mums švarų, vieningą viso kodo bazės vaizdą, nereikalaujant išsklaidytų IDE patarimų. 4. Clean Code – The Documentation You Don’t Need to Maintain Galiausiai, labiausiai nepakankamai įvertinta dokumentacijos forma taip pat yra ta, kurią kūrėjai gerbia mažiausiai, kol jiems to tikrai reikia: clean code. Komentarų amžius. Specs drift. READMEs gauti ignoruojami. JavaDocs gali tapti neaktyvus. Bet gerai parašytas kodas – aiškus, tyčinis ir išraiškingas – ir dokumentacijos. yra Kaip garsiai pasakė dėdė Bobas, „Švarus kodas skaito kaip gerai parašyta proza.“ And in practice, that means: 
 
 
 
 
 
 
 Klasės ir metodai su pavadinimais, kurie atskleidžia jų paskirtį Funkcijos, kurios daro vieną dalyką ir daro jį gerai Domino terminologija naudojama nuosekliai Nėra išminties dėl savęs Nėra „nuostabaus elgesio“ paslėptų šalutinių poveikių jokių nereikalingų gilių abstrakcijų, reikalaujančių doktorantūros suprasti Švarus kodas yra vienintelis artefaktas, garantuotas išgyventi refaktoriams, sprintams, darbuotojų apyvartai ir organizaciniam chaosui. Dėl sistemos elgesio. is A simple rule emerged for us over time:  If you need a paragraph of comments to explain a method, the real problem is the method. Kai kodas yra išraiškingas, viskas tampa lengviau → „JavaDocs“ tampa lengvesnė ir labiau orientuota → README susiaurėja, nes įdiegimas tampa akivaizdus → specifikacijos tampa aiškesnės, nes domeno modelis atspindi verslo žodyną. Švarus kodas nepašalina dokumentacijos poreikio; jis Tą Ankščių Ji užtikrina, kad visos kitos dokumentacijos formos - specs, READMEs, JavaDocs - patvirtina tiesą, o ne kompensuoja neaiškią įgyvendinimą. In the end, clean code is the documentation that demands no maintenance, no CI integration, and no tooling. It’s the most honest, reliable explanation of what the system actually does. Bringing It All Together — A Living Documentation Pipeline Bringing It All Together — A Living Documentation Pipeline After refining how we wrote documentation, the final step was to ensure it wasn’t just created—but continuously delivered and always accessible. For that, we built a documentation pipeline that turned our specs, README files, and JavaDocs into a single, unified  . living documentation portal Kadangi mes norėjome, kad mūsų dokumentai būtų kuo arčiau mūsų kodo, mes nusprendėme viską įdiegti per Github Pages nėra ypatinga Github (GitLab, pavyzdžiui, taip pat turi GitLab puslapius) - tai dar viena tvarkinga funkcija populiarių versijų kontrolės sistemų aš rekomenduoju toliau skaityti - . GitHub Pages Linkų Norėdami surinkti viską į suderintų puslapių rinkinį, mes naudojome Sphinx. "Sphinx" yra galingas dokumentacijos generatorius, parašytas "Python".Jis paima šaltinio failus, parašytus reStructuredText arba Markdown, ir verčia juos į įvairius išvesties formatus, įskaitant HTML, PDF ir ePub. „Sphinx“ tvarkė struktūrą, navigaciją ir temą. „Doxygen“ maitino „Sphinx“ automatiškai generuojamomis „JavaDocs“ programomis, naudojant Plugin, suteikiant mums visiškai naršomą API nuorodą tiesiai iš šaltinio kodo. tuo tarpu šaknų README tarnavo kaip tiesioginis įėjimo taškas kūrėjams, tyrinėjantiems saugyklą, sklandžiai susieti su sukurta dokumentacijos svetaine. Breathe Kiekvienas susijungimas į pagrindinį sukėlė CI darbą, kuris atstatė dokumentus, užtikrindamas, kad portalas atspindėtų naujausius kodo pakeitimus, API atnaujinimus ir dizaino sprendimus. Niekas nebuvo izoliuotas. Niekas nereikėjo rankinio sinchronizavimo. This turned our documentation from a static artifact into a continuously updated ecosystem that developers actually used, because it was integrated directly into their daily workflow and lived right alongside the code. Conclusion — Documentation Is Our Responsibility, Not Our Burden Išvada – dokumentacija yra mūsų atsakomybė, o ne našta Galiausiai, dokumentų rašymas nėra neprivalomas. Tai yra dalis mūsų, kaip inžinerijos specialistų, darbo. Ateities komandos nariai priklauso nuo to. Įsijungimas priklauso nuo to. Nuo to priklauso priežiūra, patikimumas ir netgi architektūrinė aiškumas. Laikydami dokumentus arti kodo, automatizuodami viską, kas gali būti automatizuota, ir pasikliaudami protingais įrankiais, tokiais kaip „Markdown“, „JavaDocs“, „Doxygen“ ir „Sphinx“, pašaliname trintį, kuris paprastai žudo dokumentų kūrimo pastangas. Kai kuriame sistemas, kurios skatina kūrėjus atnaujinti dokumentus taip pat lengvai, kaip jie rašo kodą, visi gauna naudos: komanda, produktas ir, svarbiausia, neturtinga siela, kuri paveldi projektą po šešių mėnesių. Gera dokumentacija nepadaro mus mažiau tingus.Jis tiesiog daro tingus suderinamas su kuriant puikią programinę įrangą.

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

Šis garso įrašas sukurtas originalia istorijos kalba!

Jei jūsų dokumentacijai atidaryti reikia dviejų paspaudimų, ji susilieja - ji jau pasenusi

About Author

KOMENTARAI

PABAIGTI ŽYMES

ŠIS STRAIPSNIS BUVO PRISTATYMAS

Related Stories

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps