Continuous documentation

Minek töltsek időt a dokumentáció megírásával, ha én úgyis értem hogyan működik? – hiszen én írtam.

A dokumentáció hiánya okozta-, és az elkészítésével kapcsolatos érzéseket sokan ismerjük. Viszont ha ez ennyire ellentmondásos, miért nincs még rá könnyű megoldás?

Open source csomagok

Ha egy 3rd party package-re akarok támaszkodni, egyből ütöm fel a github-ot, és bújom a dokumentációt, hogy a lehető legrövidebb idő alatt megértsem miként kell használni, milyen interface-eken keresztül tudom beépíteni. Ha őszinte akarok lenni, kevésbé érdekel, hogy hogyan működik, csak működjön. Szeretem a jó minőségű csomagokat, mert egyszerűsítik a munkát, kényelmes őket használni, és sokban nyomós okokból meg is bízom: a weekly download counter milliós nagyságrenden van (ennyi fejlesztő nem tévedhet), használható a leírás, aktívan karbantartják a kódot, zöldek a tesztek, nincs piros security warning a csomagkezelőben telepítésnél, és „a másik projeken is rendben volt”.

Ez is jól mutatja, hogy másoknak úgy tudsz hatékonyan átadni kódot, ha az megfelel a „jó minőség” kritériumainak. Ez egy open source csomag esetében kényszer is, mert senki nem ér rá elmagyarázni egyesével a programozóknak, hogy hogyan kell beépíteni. A csomagok elkészítésének módszertana a háttérben közben változatos lehet, gyakran mire elkezded használni, több tucat contributor sok száz órányi kollaborációja van mögötte: kutatás, kódolás, tesztelés, tapasztalatszerzés, újrakezdés, egyeztetések, dokumentáció írás stb.

Alkalmazásaink moduljai

Ugyanezt tapasztalom, mikor csapatban fejlesztünk egy rendszert: kellő tervezés és dokumentáció nélkül újra és újra előkerülnek ugyanazok a kérdések.
Ha egy jó specifikáció segít közös nyelvet beszélni a projektben és használható rendszertervvel meghatározzuk a komponensek és modulok kapcsolódási pontjait úgy, hogy azokról mindenki számára egyértelműek az interface-ek, akkor már sokkal jobb helyzetben vagyunk. Viszont számtalanszor láttam olyat is, hogy a tervek ellenére elkezdtek burjánzani a mellékszálak, előre ki nem talált részekre gyakran felesleges egyedi megoldások, és nehezen érthető komplexitás került.

Egy „monolit vs microservice” podcast-ból beugrik egy ide illő gondolat:

nem baj, ha a rendszerben van szemét, de azok legyenek izolált kis szemétkupacok

Ennél kevésbé volt szofisztikált az eredeti megfogalmazás, de az üzenet lényege az volt, hogy ha az architektúrád rendben van, akkor az alkalmazás jó állapotát könnyebb megőrizned, mert meghagyod a lehetőséget arra, hogy komponensenként hibát keress, tesztelj, javíts, refaktorálj. Viszont ezeknek az építőelemeknek össze kell kapcsolódnia, amihez át kell tudnod adni fő konpeciókat.

Az sem feltétlen baj, ha egy package-hez nincs részletes dokumentáció, ha az külső csomag, így nem kell módosítani, csak használni. Azonban ha az alkalmazásod egy komponenséről van szó, amivel nagy eséllyel még lesz dolgod, akkor a belső működést is célszerű könnyen érthetővé tenni, hogy gyorsan fel lehessen venni a fonalat, ha át kell adnod, vagy ha újra elő kell venned.

A komplex részek akkor is megérdemelnek pár sor leírást, ha jól olvasható a kód. Ezt feljegyezhetünk DocBlock comment-ekben, de mivel azok erősen kontextushoz kötöttek (adott osztályhoz, metódushoz, kódrészlethez kapcsolódnak), nem ideálisak átfogó koncepció kifejtésére. Ebben segíthet, ha van módszered az alkalmazás forrásához tartozó leírás folyamatos bővítésére. Ezt azért nem fejtem ki, mert született egy páratlan cikk a megközelítésről, amit itt olvashatsz:

infoq.com/articles/continuous-documentation

Javaslatok

A gyakorlati megvalósítás a cikk alapján kézenfekvő, mégis megosztok pár gondolatot kiegészítésképpen:

• a kód és a dokumentáció írása közben gondolkozz néha az olvasó fejével is – aki lehetsz akár Te is pár hét múlva – és azokat a részeket jegyezd fel, ami számodra sem volt egyértelmű. Ezáltal egyszerre fejlesztői jegyzetet és dokumentációt is készítesz.
• készíts egy "docs" directory-t a komponenseidhez a verziókövetőben, és ebben építsd fel a leírást.
• használj markdown-t, képeket, mermaid diagramokat és code snippet-eket a leírásban
• a hosszabb magyarázatokat, amit máskor a kódban írnál, írd meg a "docs"-ban, és linkeld be egy @see-vel
• a fentit alkalmazhatod visszafelé is, pl code snippet-ek helyett, akár a szövegesen kifejtett story-k és a tesztek összelinkelésére stb.
• a codereview keretében nézzétek át, tartsátok naprakészen a leírásokat is!

Pro tip: Ha a technikai tervezést is a repository-ban kezded el, tulajdonképpen a teljes SDLC alatt egy folyamatosan fejlődő leírásod lesz, ami a végén a rendszertervből egy részletes technikai dokumentációvá válik úgy, hogy közben minden közreműködő gyakorolja a dokumentálást is, ami sok esetben hasonlóan rávezet a helyes megoldásokra, mint a rubber duck debugging: „marhaságot mégsem írok le”.