a Kóddokumentáció értéke

a Kóddokumentáció könnyen érthető képek és írott leírások gyűjteménye, amelyek elmagyarázzák, mit csinál egy kódbázis, és hogyan lehet használni.

ez lehet egyszerű magyarázó megjegyzéseket fenti funkciók és blokkok, vagy egy teljes értékű fejlesztői kézikönyv, kiegészítve előíró stílusú dos-and-don ‘ ts, áttekintések minden része az alkalmazás, és megközelítések a leggyakoribb típusú kódolási feladatokat.

gyakran a legjobb, ha boldog közeget találunk e két véglet között, amikor tudatosan úgy döntünk, hogy kommentáljuk a kódunkat, és egyszerű nyelven felvázoljuk a kódbázis gnarlier területeit.

miért dokumentálja a kódot?

miért megy a baj írásban a kódot, ahelyett, hogy csak írásban kódot? Nem lenne ez amúgy is eredményesebb?

mentális mentési pontok

a dokumentáció olyan, mint egy mentális mentési pont azokra az időkre, amikor végre megkapod, mi történik a nap végén, és nem akarod elveszíteni a lendületet. A jól dokumentált kód biztosítja, hogy amikor holnap reggel (vagy több hónap múlva) vissza kell merülnie, akkor nem kell annyi időt szánnia a sebességre.

a dokumentált kód újrafelhasználásra kerül

a használt könyvtár és a nem használt könyvtár közötti különbség gyakran a dokumentációjában rejlik.

ki szeretne dokumentálatlan nyílt forráskódú könyvtárat használni, vagy hozzájárulni egy dokumentálatlan projekthez? Szinte senki.

a legtöbb esetben inkább egy kevésbé hatékony könyvtárat használ, amely dokumentumokat tartalmaz. Miért? Mivel a dokumentáció más információs pontokat közvetít a kódbázisról. A fejlesztők úgy vélik, hogy a projekt megéri az időt és az energiát, hogy írjon róla közérthető nyelven, így bárki, aki lehet, hogy érdekelt lehet gyorsan elkezdeni, és megtanulják, hogyan működik, és miért fontos döntéseket hoztak.

egy új, érdekes és jól dokumentált projekt megtalálása a kedvenc nyelvén nagyon izgalmas és szórakoztató lehet. Nézzük meg a szélsőséges alternatívát: szükség van egy nem dokumentált kódkönyvtár használatára, és potenciálisan hozzájárulhat egy látszólag bizánci kódbázishoz… elég fájdalmasan hangzik, igaz?

akkor miért nem dokumentálta a saját kódját?

a kód dokumentálása a jó kód megírásának része

a jó kód sarokköve a karbantarthatóság, érthető, olvasható dokumentációval érhető el.

a kód dokumentálásának többféle módja van:

• jó nevek kiválasztása változókhoz és függvényekhez
• rövid megjegyzések elhagyása a kódon belül, hogy segítsen kontextust adni a jövőbeli olvasóknak
• szemléltető képek hozzáadása, például szekvencia és entitáskapcsolati diagramok
• API dokumentumok biztosítása, az egyes osztályok, módszerek, argumentumok és visszatérési értékek leírása
• statikusan gépelt nyelv, például TypeScript (típusok) használata mint dokumentáció)

hasonlítson össze két példát

tegyük fel, hogy valamilyen adatot kap egy háttér API-ból, és” beilleszti ” – konvertálja egy hasznosabb alakzattá egy front-end UI. Íme az első a két lehetséges megoldás közül.

// wdgt.jsexport const converter = (w) => { wdgtHdr = { name: w.nm, id: w.id, ts: w.lastTS } wdgtDtl = { dtlId: w.dtlId, dtlName: w.dtlNm, openTS: w.oTS, closeTS: w.cTS } wdgtRev = w.revs.map((r) => { const { note, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS } = r const rr = { assocId: prsn1Id, assoc: `${prsn1Fn} ${prsn1Ln}`, amount: amt, note: note, revTS: cTS, } return rr } return { wdgtHdr, wdgtDtl, wdgtRev }}

a fenti kód fájdalmas lehet. A név alapján láthatja, hogy ez valamiféle átalakító, amely a w értéket veszi fel.

úgy tűnik, hogy egy fejlécet ad vissza, talán részleteket, és valamit, amit revs-nek hívnak. Egyébként honnan jött a fordulatszám? Természetesen nincsenek részletek a bejövő változónevekről note, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS… vagy van? A rr a returned rev rövidítése? Ki tudja.

nézzük meg a második példát.

// widget_utils.ts// widgetConverter :: widgetRespDTO -> widgetexport const widgetConverter = (wResp: widgetRespDTO): Widget => { const widgetHeader: WidgetHeader = { name: wResp.nm, id: wResp.Id, ts: wResp.lastTS), // timestamp } const widgetDetail: WidgetDetail = { id: wResp.widgetId, name: wResp.dtlNm, openTS: wResp.oTS, // timestamp closeTS: wResp.cTS // timestamp } // is nested inside of WidgetRespDTO // .map -> const widgetRevisions: ReadonlyArray<WidgetRevision> = wResp.revs.map((wRevs: WidgetRevisionsRespDTO): WidgetRevision => { // how that other team names their variables...! const { cmt, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS } = wRevs const comment: string = cmt const associateId: string = prsn1Id const associateName: string = `${prsn1Fn} ${prsn1Ln}` const amount: number = amt const revisionTS: number = cTS // unix timestamp, and "closeTS" fyi return { associateId, associateName, amount, comment, revisionTS, } } return { widgetHeader, widgetDetail, widgetRevisions, }}

Wow, milyen más! Ez a függvény util fájlban van, így a fő fájl már kevésbé zsúfolt. A sima JavaScript helyett gépírással is meg van írva, így a típusmeghatározások előnye segít nekünk.

a widgetRespDTOs-t widget s-re konvertáljuk. Létrehozunk egy widgetHeader és egy widgetDetail értéket, ami könnyen látható. Azt is megértjük, hogy mi az oTS és cTS. Elmondhatjuk, hogy WidgetRevisionsRespDTO s a WidgetRespDTO belsejében van beágyazva.

valaki nagyon kedvesen átnevezte a bejövő változókat, így mindenki, aki látja ezt a kódot, tudja, mik azok. Végül azt látjuk, hogy a Widget – nak a visszaadott {widgetHeader, widgetDetail, widgetRevisions} objektumból kell állnia, mivel meg kell egyeznie a tetején megadott Widget visszatérési típussal.

melyik kódot használnád jobban?

ki részesül előnyben?

a jól dokumentált kód sok ember számára előnyös:

Junior developers

mivel egyszerű és könnyen érthető, a dokumentáció segít a junior fejlesztőknek és az új csapattagoknak abban, hogy magabiztosan ugorjanak be egy kódbázisba. Ez megakadályozza a frusztrációt és a feladat korai elhagyását, mert túl gyorsan bonyolulttá válik.

a junior fejlesztők számára is hasznos, ha saját dokumentációt írnak, hogy megoszthassák a kódjukat másokkal, és így jobban megértsék a kódjukat.

Senior developers

azáltal, hogy időt vesz igénybe, hogy dokumentálja most, senior devs kevesebb időt töltenek elmagyarázza a kódot másoknak a jövőben.

összetettebb kódot is írhatnak. Az egyszerű nyelvű dokumentáció lehetővé teszi mások számára, hogy fekete dobozként használják, anélkül, hogy meg kellene érteniük a belső működést.

Teams & nyílt forráskódú projektek

a személyi változások óriási lassulást okozhatnak egy projektben. A naprakész és jól dokumentált kód biztosítékként szolgálhat az ilyen lassulások ellen, és lehetővé teszi a fennmaradó csapattagok számára, hogy visszalépjenek, magas szintről felülvizsgálják a kódot, és döntsenek a legjobb lépésekről, és szükség esetén új alkalmazottakat vegyenek fel.

Ön

a kód dokumentálásakor össze kell foglalnia. A megfelelő összefoglalás érdekében képesnek kell lennie arra, hogy megértse, a különböző részeket egyszerre tartva a fejében. A dokumentáció megírása vagy közreműködése egy gyorsbillentyű ahhoz, hogy valóban megértsük a kódbázist, hatalmas hozzájárulásokat tegyünk, és úgy érezzük magunkat, mint egy nagyszerű csapat nagy része.

a jó dokumentáció kiszáríthatja kódolási tapasztalatainkat

programozóként valószínűleg hallottál már a ne ismételje meg magát elvről, mint a tiszta és tömör kód írásának kulcsáról. Ahelyett, hogy ugyanazt a kódblokkot többször megismételné, írjon egy olyan függvényt, amelyet egyszer lehet írni, és az egész alkalmazásban alkalmazható.

ugyanígy Önnek és csapatának sem szabadna hasonló problémákba ütköznie, majd újra feltalálnia a kereket minden alkalommal, amikor megpróbálja megoldani őket. Például hallottál már valaha az egyik munkatársadról, vagy azon kaptad magad, hogy azt mondod:

“Agh, megoldottam valami nagyon hasonlót, de soha nem emlékszem, hogyan csinálom, amikor felmerül… Le kéne írnom valahova, nem?”

ezután azon kapja magát, hogy újra és újra ugyanazokat a Stack Overflow szálakat szkenneli.

Mentsd meg magad és munkatársaid ezt a bánatot a száraz elv szellemének követésével és egy olyan dokumentum megírásával, amelyet minden alkalommal alkalmazhatsz, amikor a kérdés felmerül! Ez segít Önnek és a csapat többi tagjának, hogy időt takarítson meg, és hatékonyabb legyen az egyszerűbb, kezelhetőbb és hatékonyabb kód írásában.

hogyan befolyásolta Önt a kóddokumentáció vagy annak hiánya?