Tokom godina, radio sam na svim vrstama projekata – velikim, malim, haotičnim, pretvorenim, „privremenim“, navodno dobro strukturiranim, i sve između. The documentation is always missing, outdated, or buried in some forgotten corner of Confluence guarded by a 2019 timestamp. Svaki projekat Treba imati dokumentaciju. Pretpostavke Svaka ekipa Oni će ga održavati ažuriranim. obećanja I svaki programer samopouzdanje kaže, "Ne brini, ja ću to napisati kasnije", što, kao što svi znamo, je dokumentacija ekvivalent kaže “Ček je u pošti.” Nakon što sam gledao ovaj ciklus koji se ponavlja više puta nego što bih htio priznati, shvatio sam nešto jednostavno, ali brutalno istinito: 
 
 Dokumentacija preživljava samo ako živi što bliže kodu – jer su programeri (uključujući i mene) lijena bića. Documentation only survives if it lives as close to the code as possible—because developers (myself included) are lazy creatures. I iz toga, došlo je do još jednog shvatanja - glavni problem sa zastarjelom dokumentacijom je činjenica da većina timova ne smatra da je dio glavnog ciklusa razvoja, ostavljajući ga za kasnije ili zbog nekoliko pre-dev specifikacija koje su već imali negde u Confluenceu. Da biste napisali značajnu dokumentaciju, prvo razmotrimo koju vrstu dokumentacije postoji za softversku komponentu: Ways to Document Code (That Developers Might Actually Use) Načini dokumentacije koda (Da programeri mogu stvarno koristiti) Nakon što prihvatite da dokumentacija mora živjeti blizu koda, sledeće pitanje je da ga strukturira. Kako U praksi, otkrio sam da dobra dokumentacija nije jedan artefakt - to je mali ekosustav slojeva, svaki služi različitoj svrsi i publici. Za taj projekt koji sam spomenuo (napisan u Java + Spring Boot), identificirali smo četiri glavne vrste dokumenata: 1. Client Specs Idealno, oni su bogati sveprisutnim jezikom i pružaju kode-agnosticirane opise poslovnih slučajeva - drugim rečima, sve što inženjer treba da doista razumije problem pri ruci. Nažalost, u stvarnosti, ovi dokumenti često završavaju pohranjen negde u Confluenceu, podijeljen s timom na početku projekta, a zatim se gotovo nikada više ne ažuriraju. Nemojte me pogrešiti: Ovi dokumenti Važno je su Ali specifikacije se razvijaju, rokovi stresa sve, a ti originalni dokumenti polako ali sigurno postaju zastarjeli temelj. Znanje o promjenjivim zahtjevima, slučajevima granica i projektnim pivotovima završava živjeti u kodu - ili još gore! - u glavama viših programera. Kako bi se to riješilo, zaustavili smo pisanje specifikacija u slučajnim Word datotekama ili stranicama Confluence koje su namenjene da budu zaboravljene i premestili ih što bliže prednjoj liniji: the code repository. Počeli smo da ih čuvamo kao Markdown (.md) datoteke unutar repo, obično u docs / fascikli. U velikim mikroslužnim okruženjima, ovi dokumenti mogu čak opravdati poseban repozitorij povezan kao Git podmodul. Za daljnje čitanje o podmodulima, preporučujem ovaj blog post - . Linkovi 2. README – The Front Door for Humans Ako su specifikacije klijenta enciklopedija, README je prednja vrata. Ironično, gotovo svaka platforma za kontrolu verzija - GitHub, GitLab, Bitbucket - automatski prikazuje README pravo na glavnoj stranici projekta. To je prva stvar koju svaki programer vidi kada stigne u repozitorij. Dobar README nije opcionalan. To je pojedinačni dokument koji se najverovatnije čita jer zahtijeva A budući da se nalazi na korijenu repo-a, programeri su više vjerojatno da će ga ažurirati dok rade na kodu. zero clicks Dobro napisan README bi trebao odgovoriti na najvažnija pitanja koja programer ima u prvih nekoliko minuta susreta s projektom: 
 
 
 
 
 
 
 Šta ova usluga/projekt/komponenta radi? - kratka svrha i kontekst - nema marketinških tokova. Kako da ga pokrenem lokalno? - upute za radno vrijeme, promjenjive okoline, podešavanja ovisnosti i bilo koje komande specifične za projekat. Kako da ga testiram? - testovi jedinica, testovi integracije, postavljanje testnih podataka i bilo koji alat koji se odnosi na test. Kako je projekt strukturiran? - kratko objašnjenje rasporeda direktorijuma, ključnih modula i gde pronaći važne dijelove koda. Kako da ga raspoređujem? skripte za raspoređivanje, CI / CD beleške, potrebne dozvole ili nijanse platforme.  links to generated docs, architecture notes, API references, and centralised design documents. Where can I read further? - README je ulazna točka u projekt. On postavlja očekivanja, skraćuje vrijeme uključivanja i daje svakom inženjeru – novom ili iskusnom – jasnu orijentaciju. 3. JavaDocs – Docs That The Compiler Annoys You Into Maintaining JavaDocs - obično nevidljivi, često zaboravljeni, ali apsolutno neophodni kada se nešto pokvari. U praksi, dokumentiranje Java projekata često pada u dvije krajnosti: ili ili jer „koda je samo-dokumentiranje.“ Istina, kao i uvek, je negde u sredini. over-commenting every trivial line no comments at all Za naš projekat, doneli smo svesnu odluku da dokumentiramo To je značilo: only what was genuinely necessary 
 
 
 
 
 koristeći sveprisutan jezik tako da su termini domena odgovarali točno onome što je bilo u poslovnim specifikacijama objašnjenje zašto iza ne očiglednih odluka, a ne ono što kod već otkriva dokumentiranje ključnih domena, interfejsa i složenih tokova posla izbegavanje zidova komentara koji jednostavno ponavljaju ime metode u verboznom obliku JavaDocs, kada se pravilno koriste, služe kao mikro-nivo dokumentacije koja razjašnjava namjeru bez ometanja koda.I za razliku od Confluence stranica, JavaDocs dolazi s ugrađenom prednošću: 
 
 Kompiler se zapravo žali kada izađu iz sinhronizacije. Ako preimenujete parametar, ali zaboravite oznaku JavaDoc, gradnja vas podsjeća. Ako izbrišete metodu, ali ostavite nestale reference za komentare, IDE će se rasvijetliti kao božićno drvce. Ovo blago trenje je upravo razlog zašto JavaDocs imaju tendenciju da ostanu točniji od drugih oblika dokumentacije - oni su uznemirujuće zanemariti. Da bismo sve održali centralizovano i izbegli „otoke dokumentacije“, takođe smo koristili . Doxygen Doxygen je široko korišćen alat za generiranje dokumentacije u razvoju softvera. Dok se uglavnom koristi u zajednici C++, koristimo ga da agregiramo JavaDocs u dosljednu, pregledivu referenciju - HTML stranicu. Ima niz značajki koje JavaDoc ne nudi, npr. dijagram klase za hijerarhije i kontekst saradnje, više sažetnih stranica i još mnogo toga. To nam je dalo čist, ujednačen pogled na čitavu bazu kodova bez oslanjanja na raspršene IDE savete. 4. Clean Code – The Documentation You Don’t Need to Maintain Konačno, najpotcenjeniji oblik dokumentacije je i onaj koji programeri najmanje poštuju sve dok im stvarno nije potreban: clean code. Komentari dob. Specs drift. READMEs se ignorišu. JavaDocs može postati stale. Ali dobro napisan kod – jasan, namjeran i ekspresivan – U dokumentaciji. je Kao što je Uncle Bob slavno rekao, “Čisti kod čita kao dobro napisana proza.” And in practice, that means: 
 
 
 
 
 
 
 Klase i metode s imenima koji otkrivaju njihovu svrhu Funkcije koje rade jednu stvar i rade je dobro Domaće terminologije korištene dosljedno Nema mudrosti za sopstvenu korist nema “iznenađenja ponašanja” skrivenih unutar nuspojava bez nepotrebno duboke abstrakcije koje zahtijevaju doktorat da razume Čist kôd je jedan artefakt garantovan za preživljavanje refaktora, sprinta, prometa osoblja i organizacijskog haosa. ponašanje u sistemu. is Jednostavno pravilo se pojavilo za nas s vremenom: If you need a paragraph of comments to explain a method, the real problem is the method. Kada je kod ekspresivan, sve ostalo postaje lakše → JavaDocs postaje lakši i fokusiraniji → README se smanjuje jer onboarding postaje očigledan → specifikacije postaju jasnije jer model domene odražava poslovni vokabular. Čisti kôd ne uklanja potrebu za dokumentacijom; to To je. Ankeri Ona osigurava da svi drugi oblici dokumentacije – speci, READMEs, JavaDocs – potvrđuju istinu umjesto da kompenziraju nejasnu implementaciju. U konačnici, čisti kod je dokumentacija koja ne zahtijeva održavanje, ne CI integraciju i ne alatizaciju. Bringing It All Together — A Living Documentation Pipeline Donosimo sve zajedno - Živa dokumentacija Pipeline Nakon što smo rafinirali kako smo napisali dokumentaciju, konačni korak je bio da se osigura da nije samo stvorena, već kontinuirano isporučena i uvijek dostupna. . living documentation portal Budući da smo želeli da naši dokumenti žive što je moguće bliže našem kodu, odlučili smo da sve implementiramo kroz Github stranice nisu specifične za Github (GitLab, na primjer, ima i GitLab stranice) - to je još jedna čista značajka popularnih sistema kontrole verzija preporučujem za daljnje čitanje - . GitHub Pages Linkovi Da bismo sve kompilirali u skup koherentnih stranica, koristili smo Sphinx. Sphinx je moćan generator dokumentacije napisan u Pythonu. On uzima izvorne datoteke napisane u reStructuredText ili Markdown i prevodi ih u različite formate izlaza, uključujući HTML, PDF i ePub. Sphinx je upravljao strukturom, navigacijom i tematizacijom. Doxygen je hranio Sphinx sa automatski generisanim JavaDocima koristeći plugin, dajući nam u potpunosti pregledljiv API referencu izravno iz izvornog koda. U međuvremenu, root README je služio kao neposredna ulazna tačka za programere koji istražuju repozitorij, bez problema povezujući se na generisanu dokumentaciju. disanje Every merge into main triggered a CI job that rebuilt the docs, ensuring the portal reflected the latest code changes, API updates, and design decisions. Nothing lived in isolation. Nothing required manual syncing. And crucially—nothing was more than a single click away. 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 Zaključak – Dokumentacija je naša odgovornost, a ne naš teret Na kraju dana, pisanje dokumentacije nije neobavezno. To je deo našeg posla kao inženjering profesionalaca. Budući kolege u timu ovise o tome. Uključivanje ovisi o tome. Održavanje, pouzdanost, pa čak i arhitektonska jasnoća ovise o tome. Ali prihvaćanje te odgovornosti ne znači da dokumentacija mora biti bolna. Držeći dokumente blizu koda, automatizirajući sve što se može automatizovati i oslanjajući se na pametne alate kao što su Markdown, JavaDocs, Doxygen i Sphinx, uklanjamo trenje koje obično ubija napore u dokumentaciji. Pretvaramo nešto što se tradicionalno osjeća kao zadatak u prirodno produženje svakodnevnog razvoja. Dokumentacija ne mora biti savršena – samo mora biti pristupačna, precizna i živa.Kada gradimo sisteme koji potiču programere da ažuriraju dokumente tako lako kao što pišu kod, svi imaju koristi: tim, proizvod i, što je najvažnije, siromašna duša koja nasledi projekt šest mjeseci kasnije. Dobra dokumentacija nas ne čini manje lijenim.To samo čini da je lijen kompatibilan s izgradnjom velikog softvera.

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

Ovaj audio je proizveden na originalnom jeziku priče!

Ako vaša dokumentacija traje dva klikova da se otvori, kongreta - već je zastarela

About Author

KOMENTARI

HANG TAGS

OVAJ ČLANAK JE PREDSTAVLJEN U

Related Stories

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps