kódová dokumentace je sbírka snadno pochopitelných obrázků a písemných popisů, které vysvětlují, co kódová základna dělá a jak ji lze použít.
mohou to být jednoduché vysvětlující Komentáře nad funkcemi a bloky nebo plnohodnotná příručka pro vývojáře, doplněná normativním stylem dos-and-don ‚ ts, přehledy každé části aplikace a přístupy k nejběžnějším typům kódovacích úkolů.
často je nejlepší najít šťastné médium mezi těmito dvěma extrémy, když se vědomě rozhodnete komentovat svůj kód a nastínit gnarlier oblasti kódové základny v prostém jazyce.
proč dokumentovat svůj kód?
proč jít do potíží s psaním o vašem kódu, namísto pouhého psaní kódu? Nebylo by to stejně produktivnější?
Mental Save Points
dokumentace je jako mental save point pro ty časy, kdy konečně dostanete to, co se děje na konci dne a nechcete ztratit dynamiku. Dobře zdokumentovaný kód zajistí, že když se budete muset zítra ráno (nebo za několik měsíců) ponořit zpět, nebudete muset trvat tolik času, abyste se dostali do rychlosti.
dokumentovaný kód se znovu použije
rozdíl mezi použitou knihovnou a nepoužívanou knihovnou často spočívá v její dokumentaci.
kdo chce použít nezdokumentovanou knihovnu s otevřeným zdrojovým kódem nebo přispět do nezdokumentovaného projektu? Skoro nikdo.
ve většině případů byste raději používali méně výkonnou knihovnu, která obsahuje dokumenty. Proč? Protože dokumentace poskytuje další informace o kódové základně. Vývojáři věří, že projekt stojí za čas a energii psát o tom v prostém jazyce, takže každý, kdo by mohl mít zájem, může rychle začít a naučit se, jak to funguje, a proč byla učiněna klíčová rozhodnutí.
nalezení nového, zajímavého a dobře zdokumentovaného projektu ve vašem oblíbeném jazyce může být velmi vzrušující a zábavné. Podívejme se na extrémní alternativu: je nutné používat nezdokumentovanou kódovou knihovnu a potenciálně přispívat ke zdánlivě byzantské kódové základně… Zní to docela bolestivě, že?
tak proč jste zdokumentovali svůj vlastní kód?
dokumentování kódu je součástí psaní dobrého kódu
základním kamenem dobrého kódu je udržovatelnost, dosažená srozumitelnou a čitelnou dokumentací.
existuje několik způsobů, jak dokumentovat kód:
- výběr dobrých názvů proměnných a funkcí
- ponechání krátkých komentářů v kódu, které pomohou dát kontext budoucím čtenářům
- přidání ilustrativních obrázků, jako jsou diagramy vztahů se sekvencemi a entitami
- poskytování dokumentů API, popisujících každou třídu, metodu, argument a návratovou hodnotu
- pomocí staticky zadaného jazyka, jako je TypeScript (typy jako dokumentace)
Porovnejte dva příklady
Řekněme, že získáváte nějaká data z backend API a“ ingressing “ to – převod do užitečnějšího tvaru pro front-end UI. Zde je první ze dvou možných řešení.
// 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 }}výše uvedený kód má potenciál být bolestivý. Podle názvu můžete vidět, že se jedná o nějaký konvertor, který bere w jako svůj param.
vypadá to, že vrací záhlaví, možná detaily a něco, co se nazývá otáčky. Kde se vlastně vzaly otáčky? Samozřejmě neexistují žádné podrobnosti o příchozích názvech proměnných note, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS… nebo existuje? Je rr zkratka pro returned rev? Kdo může říct.
podívejme se na druhý příklad.
// 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, }}Páni, jak odlišné! Tato funkce je v souboru util, takže hlavní soubor je již méně přeplněný. Je také napsán v TypeScript místo prostého JavaScriptu, takže máme výhodu definic typu, které nám pomohou vést.
převádíme widgetRespDTO s na widgets. i když jsme zkráceni, máme plné znalosti o tom, co wResp je. Vytváříme widgetHeader a widgetDetail, to je snadné vidět. Chápeme také, co jsou oTS a cTS. Můžeme říci, že WidgetRevisionsRespDTO s jsou vnořeny uvnitř WidgetRespDTO.
někdo velmi laskavě přejmenoval příchozí proměnné, takže každý, kdo vidí tento kód, ví, co jsou. Nakonec vidíme, že Widget musí být složen z vráceného objektu {widgetHeader, widgetDetail, widgetRevisions}, protože musí odpovídat typu návratu Widget zadanému nahoře.
jaký kód byste se cítili lépe?
kdo těží?
dobře zdokumentovaný kód prospívá mnoha lidem:
Junior developers
protože je to v jednoduchém jazyce a snadno pochopitelné, dokumentace pomáhá juniorským vývojářům a novým členům týmu cítit jistotu, že skočí do kódové základny. Tím se zabrání frustraci a předčasnému opuštění úkolu, protože se příliš rychle komplikuje.
je také užitečné pro juniorské vývojáře psát vlastní dokumentaci, aby mohli sdílet svůj kód s ostatními, a tak mohou lépe porozumět jejich kódu.
starší vývojáři
tím, že čas dokumentovat nyní, starší devs tráví méně času vysvětlovat svůj kód ostatním v budoucnu.
mohou také psát složitější kód. Dokumentace prostého jazyka umožňuje ostatním používat ji jako černou skříňku, aniž by museli rozumět vnitřnímu fungování.
týmy & open source projekty
personální změny mohou projektu přinést obrovské zpomalení. Aktuální a dobře zdokumentovaný kód může sloužit jako pojištění proti takovým zpomalením a umožnit zbývajícím členům týmu udělat krok zpět, zkontrolovat kód z vysoké úrovně a rozhodnout o nejlepším postupu vpřed, a v případě potřeby, na palubě nových zaměstnanců.
vy
při dokumentování kódu je nutné jej shrnout. Abyste to mohli správně shrnout, musíte být schopni to pochopit a současně držet různé části v hlavě. Psaní nebo přispívání do dokumentace je zkratka pro skutečné pochopení codebase, dělat obrovské příspěvky, a cítit se jako velká část skvělého týmu.
dobrá dokumentace může vyschnout naše zkušenosti s kódováním
jako programátor jste pravděpodobně slyšeli o principu neopakujte se jako klíč k psaní čistého a stručného kódu. Namísto opakování stejného bloku kódu několikrát napište funkci, kterou lze zapsat jednou a použít v celé aplikaci.
stejným způsobem byste vy a váš tým neměli narazit na podobné problémy a poté znovu objevit kolo pokaždé, když se je pokusíte vyřešit. Například, už jste někdy slyšeli jednoho z vašich spolupracovníků nebo jste zjistili, že říkáte:
“ Agh, vyřešil jsem něco velmi podobného, ale nikdy si nepamatuji, jak to dělám, když to přijde… Asi bych si to měl někde napsat, co?“
pak zjistíte, že znovu a znovu skenujete stejná vlákna přetečení zásobníku.
Zachraňte sebe a své spolupracovníky tento zármutek následováním ducha suchého principu a psaním dokumentu, který můžete použít pokaždé, když se problém objeví! To vám a ostatním ve vašem týmu pomůže ušetřit čas a být efektivnější při psaní jednoduššího, zvládnutelnějšího a efektivnějšího kódu.
jak vás ovlivnila dokumentace kódu nebo její nedostatek?