Gadu gaitā esmu strādājis pie visu veidu projektiem - lieliem, maziem, haotiskiem, pārmērīgi inženieriskiem, "laicīgiem", domājams, labi strukturētiem un visu starpā. The documentation is always missing, outdated, or buried in some forgotten corner of Confluence guarded by a 2019 timestamp. Katrs projekts Lai būtu dokumentācija. Prasības Katra komanda Viņi to atjauninās. solījumi Un katrs izstrādātājs pārliecinoši saka: "Neuztraucieties, es to uzrakstīšu vēlāk", kas, kā mēs visi zinām, ir dokumentācija, kas atbilst teiktajam: “Šekss ir pa pastu.” Pēc tam, kad redzēju, ka šis cikls atkārtojas vairāk reižu, nekā es gribētu atzīt, es sapratu kaut ko vienkāršu, bet brutāli patiesu: 
 
 Dokumentācija izdzīvo tikai tad, ja tā dzīvo pēc iespējas tuvāk kodam, jo izstrādātāji (ieskaitot mani) ir slinks radījumi. Documentation only survives if it lives as close to the code as possible—because developers (myself included) are lazy creatures. Un no tā nāca vēl viena izpratne - galvenā problēma ar novecojušu dokumentāciju ir fakts, ka lielākā daļa komandas to neuzskata par daļu no galvenā attīstības cikla, atstājot to vēlāk vai padarot par pienākumu ar pāris iepriekšējām specifikācijām, kas viņiem jau bija kaut kur Confluence. Lai uzrakstītu nozīmīgu dokumentāciju, vispirms apspriediet, kāda veida dokumentācija ir pieejama programmatūras komponentam: Ways to Document Code (That Developers Might Actually Use) Veidi, kā dokumentēt kodu (ko izstrādātāji faktiski varētu izmantot) Kad jūs piekrītat, ka dokumentācijai ir jādzīvo tuvu kodam, nākamais jautājums ir Lai to strukturētu. Kā Praksē esmu atklājis, ka laba dokumentācija nav viens artefakts - tā ir maza slāņu ekosistēma, katra kalpo atšķirīgam mērķim un auditorijai. Šajā projektā, kuru es minēju (rakstīts Java + Spring Boot), mēs identificējām četrus galvenos doku veidus: 1. Client Specs Ideālā gadījumā tie ir bagāti ar visuresošu valodu un nodrošina kodu-agnostikas biznesa gadījumu aprakstus - citiem vārdiem sakot, viss, kas inženierim ir nepieciešams, lai patiesi saprastu problēmu. Diemžēl realitātē šie dokumenti bieži vien tiek glabāti kaut kur Confluence, koplietoti ar komandu projekta sākumā un pēc tam gandrīz nekad vairs nav atjaunināti. Nesaprotiet mani nepareizi: šie dokumenti Svarīgi ir. ir Zināšanu iegūšanai no domēna ekspertiem vajadzētu būt augstākajai prioritātei jebkurai inženieru komandai. bet specifikācijas attīstās, termiņi stresa ikvienam, un šie oriģinālie dokumenti lēnām, bet droši kļūst par novecojušu pamatu. Zināšanas par mainīgajām prasībām, priekšrocību gadījumiem un projekta pīlāriem beidzas dzīvot kodā - vai vēl sliktāk! - vecāko izstrādātāju galvās. Lai to novērstu, mēs pārtraucām rakstīt specifikācijas izlases Word failos vai Confluence lapās, kas paredzētas aizmirstam, un pārvietojām tos pēc iespējas tuvāk priekšējai līnijai: the code repository. Mēs sākām tos glabāt kā Markdown (.md) failus repo iekšpusē, parasti dokos / mapēs. Lielās mikroservisa vidēs šie dokumenti var pat attaisnot īpašu repozitoriju, kas saistīts kā Git apakšmodulis. Turpmākai lasīšanai par apakšmoduliem, es ļoti iesaku šo emuāru - . LINK 2. README – The Front Door for Humans Ja klientu specifikācijas ir enciklopēdija, README ir durvis uz priekšu.Un tomēr tas ir viens no visvairāk aizmirsto dokumentācijas gabaliem programmatūras projektos. Ironiski, gandrīz katra versijas kontroles platforma - GitHub, GitLab, Bitbucket - automātiski atskaņo README tieši galvenajā projekta lapā.Tas ir pirmā lieta, ko jebkurš izstrādātājs redz, kad nokļūst repozitorijā.Neskatoties uz to, READMEs bieži vien ir šokējoši tukši, sāpīgi novecojuši vai piepildīti ar briesmīgo "VISI: rakstiet dokumentāciju vēlāk", kas, protams, nekad nenotiek. Labs README nav obligāts. tas ir viens dokuments, kas visticamāk tiks faktiski izlasīts, jo tas prasa Un tāpēc, ka tas atrodas repo saknē, izstrādātāji, visticamāk, to atjauninās, strādājot pie koda. zero clicks Labi uzrakstītam README būtu jāatbild uz svarīgākajiem jautājumiem, kas izstrādātājiem rodas pirmajās minūtēs, kad viņi saskaras ar projektu: 
 
 
 
 
 
 
 Ko šis pakalpojums / projekts / komponents dara? - īss mērķis un konteksts - nav mārketinga plūsmas. Kā to palaist lokāli? - izpildes laika norādījumi, vides mainīgie, atkarību iestatījumi un jebkuras projekta specifiskās komandas. Kā es to pārbaudīšu? - vienības testus, integrācijas testus, testa datu iestatījumus un jebkādus ar testu saistītus rīkus. Kā projekts ir strukturēts? - īss izskaidrojums par direktoriju izkārtojumu, galvenajiem moduļiem un to, kur atrast svarīgās koda daļas. Kā to izvietot? izvietošanas skripti, CI / CD piezīmes, nepieciešamās atļaujas vai platformas nianses. Kur es varu lasīt tālāk? - saites uz ģenerētiem dokumentiem, arhitektūras piezīmēm, API atsauces un centralizētiem dizaina dokumentiem. README ir vārtiens uz projektu, kas nosaka cerības, samazina uzstādīšanas laiku un dod katram inženierim – jaundzimušajam vai pieredzējušam – skaidru orientāciju. 3. JavaDocs – Docs That The Compiler Annoys You Into Maintaining JavaDocs - parasti neredzami, bieži aizmirsti, bet absolūti būtiski, kad kaut kas pārtraucas. Praksē Java projektu dokumentēšana bieži nonāk divās galējībās: vai nu vai Jo "kods ir pašdokumentējošs." Patiesība, kā vienmēr, ir kaut kur vidū. over-commenting every trivial line no comments at all Mūsu projektam mēs izdarījām apzinātu lēmumu dokumentēt Tas nozīmēja: only what was genuinely necessary 
 
 
 
 
 izmantojot visaptverošu valodu, lai domēna termini atbilstu tieši tam, kas bija biznesa specifikācijās izskaidrojot iemeslus, kāpēc aiz acīmredzamiem lēmumiem, nevis to, ko kods jau atklāj dokumentēt galvenās domēna klases, saskarnes un sarežģītās darba plūsmas izvairīties no komentāru sienām, kas vienkārši atkārto metožu nosaukumu verbozā formā Ja tiek izmantots pareizi, JavaDocs kalpo kā mikro līmeņa dokumentācija, kas precizē nodomu, neapgrūtinot kodu.Un atšķirībā no Confluence lapām, JavaDocs ir iebūvēta priekšrocība: 
 
 Kompileris faktiski sūdzas, kad tie nonāk sinhronizācijā. Ja pārdēvējat parametru, bet aizmirstat JavaDoc tagu, būve atgādina jums. Ja jūs izdzēsiet metodi, bet atstājat nepastāvīgas komentāra atsauces, IDE apgaismojas kā Ziemassvētku eglīte. Šī maiga berze ir tieši iemesls, kāpēc JavaDocs mēdz palikt precīzāki nekā citas dokumentācijas formas - tās ir kaitinošas, lai aizmirstu. Lai saglabātu visu centralizētu un izvairītos no “dokumentācijas salām”, mēs arī izmantojām . Doxygen Doxygen ir plaši izmantots dokumentācijas ģeneratora rīks programmatūras izstrādē. Kaut arī tas galvenokārt tiek izmantots C++ kopienā, mēs to izmantojām, lai apkopotu JavaDocs uz konsekventu, pārlūkojamu atsauci - HTML lapu. Tas mums deva tīru, vienotu priekšstatu par visu kodu bāzi, nepaļaujoties uz izkliedētiem IDE padomiem. 4. Clean Code – The Documentation You Don’t Need to Maintain Visbeidzot, visvairāk nenovērtētā dokumentācijas forma ir arī tā, kuru izstrādātāji respektē vismazāk, kamēr viņiem to patiešām vajag: clean code. Komentāri vecums. Specs drift. READMEs tiek ignorēti. JavaDocs var kļūt stale. Bet labi uzrakstīts kods - skaidrs, apzināts un izteiksmīgs - Dokumentācijas materiāli. ir Kā to slavenais tēvocis Bobs teica, “Tīrs kods lasāms kā labi uzrakstīta prosa.” Praksē tas nozīmē: 
 
 
 
 
 
 
 klases un metodes ar nosaukumiem, kas atklāj to mērķi Funkcijas, kas dara vienu lietu un dara to labi Domēna terminoloģija tiek izmantota konsekventi visā Nav gudrības paša labā Nav “pārsteidzošas uzvedības”, kas slēpjas blakusparādībās nav nevajadzīgi dziļas abstrakcijas, kas prasa PhD, lai saprastu Tīrs kods ir vienīgais artefakts, kas garantēts, lai izdzīvotu refaktorus, sprintus, darbinieku apgrozījumu un organizatorisko haosu. Par sistēmas uzvedību. is Laika gaitā mums parādījās vienkāršs noteikums: If you need a paragraph of comments to explain a method, the real problem is the method. Kad kods ir izteiksmīgs, viss pārējais kļūst vieglāks → JavaDocs kļūst vieglāks un koncentrētāks → README sašaurinās, jo iekļaušana kļūst acīmredzama → specifikācijas kļūst skaidrākas, jo domēna modelis atspoguļo biznesa vārdnīcu. Tīrs kods neizslēdz nepieciešamību pēc dokumentācijas; tas Tā ir. Ankeri Tas nodrošina, ka visas pārējās dokumentācijas formas - specs, READMEs, JavaDocs - apstiprina patiesību, nevis kompensē neskaidru īstenošanu. Galu galā, tīrs kods ir dokumentācija, kas neprasa uzturēšanu, nav CI integrācijas un nav rīku. Bringing It All Together — A Living Documentation Pipeline To visu apvienojot - dzīvs dokumentācijas cauruļvads Pēc tam, kad mēs pilnveidojām to, kā mēs rakstījām dokumentāciju, galīgais solis bija nodrošināt, ka tā netiek vienkārši izveidota, bet tiek nepārtraukti piegādāta un vienmēr ir pieejama. . living documentation portal Tā kā mēs vēlējāmies, lai mūsu dokumenti būtu pēc iespējas tuvāk mūsu kodam, mēs nolēmām visu izvietot caur Github Pages nav īpaša Github (GitLab, piemēram, ir arī GitLab lapas) - tas ir vēl viena tīra iezīme populāro versiju kontroles sistēmu es ieteiktu tālākai lasīšanai - . GitHub Pages LINK Lai sagatavotu visu kopumu kohēzijas lapām, mēs izmantojām Sphinx. Sphinx ir spēcīgs dokumentācijas ģenerators, kas rakstīts Python. tas ņem avota failus, kas rakstīti reStructuredText vai Markdown un tulko tos dažādos izejas formātos, tostarp HTML, PDF un ePub. Sphinx apstrādāja struktūru, navigāciju un tēmu. Doxygen baro Sphinx ar automātiski ģenerētām JavaDocs, izmantojot Plugin, kas mums sniedz pilnībā pārlūkojamu API atsauci tieši no avota koda.Tajā pašā laikā saknes README kalpoja kā tūlītējs ievades punkts izstrādātājiem, kuri izpētīja repozitoriju, bezgalīgi savienojot ģenerēto dokumentācijas vietni. elpošana Katra apvienošanās galvenajā izraisīja CI darbu, kas atjaunoja dokumentus, nodrošinot, ka portāls atspoguļo jaunākās koda izmaiņas, API atjauninājumus un dizaina lēmumus. Nekas nedzīvoja izolēti. Nekas neprasa manuālu sinhronizāciju. Tas pārvērta mūsu dokumentāciju no statiska artefakta nepārtraukti atjauninātajā ekosistēmā, ko izstrādātāji faktiski izmantoja, jo tas tika tieši integrēts viņu ikdienas darbplūsmā un dzīvoja tieši blakus kodam. Conclusion — Documentation Is Our Responsibility, Not Our Burden Secinājums – dokumentācija ir mūsu atbildība, nevis mūsu slogs Galu galā, dokumentācijas rakstīšana nav obligāta. Tā ir daļa no mūsu darba kā inženieru profesionāļiem. Nākotnes komandas biedri ir atkarīgi no tā. Onboarding ir atkarīgs no tā. Tehniskā apkope, uzticamība un pat arhitektūras skaidrība ir atkarīga no tā. bet šo atbildību pieņemšana nenozīmē, ka dokumentācijai ir jābūt sāpīgai. Saglabājot dokumentus tuvu kodam, automatizējot visu, ko var automatizēt, un paļaujoties uz viedajiem rīkiem, piemēram, Markdown, JavaDocs, Doxygen un Sphinx, mēs novēršam berzi, kas parasti nogalina dokumentācijas centienus. Kad mēs izveidojam sistēmas, kas mudina izstrādātājus atjaunināt dokumentus tikpat viegli, kā viņi raksta kodu, visi gūst labumu: komanda, produkts un, pats galvenais, nabadzīgā dvēsele, kas pēc sešiem mēnešiem manto projektu. Laba dokumentācija nepadara mūs mazāk slinkus.Tas tikai padara slinkumu saderīgu ar lielisku programmatūras veidošanu.

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 audio ir izveidots stāsta oriģinālvalodā!

Ja jūsu dokumentācija aizņem divus klikšķus, lai to atvērtu, tas ir jau novecojis

About Author

KOMENTĀRI

PAKARINĀT TAGUS

ŠIS RAKSTS TIKS PĀRSTRĀDĀTS

Related Stories

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps