Kód Dokumentace: Kompletní Průvodce Začátečníka
Jsi málo způsobů, jak do své první programátorské práce, a věci jsou stále jednodušší. Nejprve, veškerý kód, se kterým jste se museli vypořádat, vás mohl přemoci a zmást, ale začínáte se tomu dostat na kloub. To je skvělé! Nyní vás zajímá, jak posunout kód, který píšete, na další úroveň. Zatímco existuje spousta věcí, dozvědět se o vaše programování zásobníku, z nichž mnohé z vás udělá lepšího programátora, existuje několik, které vám bude sloužit bez ohledu na to, co zásobníku, ve kterém pracujete. Jedním z nich je kódová dokumentace.
mnoho vývojářů nepíše dostatek dokumentace, buď proto, že nevidí hodnotu, nebo proto, že mají pocit, že nemají čas. Nemusíte být jedním z těchto vývojářů. S trochou času a hodně praxe, můžete přidat dokumentaci pro váš kód, díky kterému je čtení radost používat pro vás i pro kohokoli jiného, kdo přijde.
dobrá dokumentace přichází v mnoha formách
když většina vývojářů myslí na dokumentaci kódu, myslí na Komentáře. Komentáře mohou být cenným doplňkem kódu, ale nejsou jedinou definicí dokumentace. Dokumentace je něco, co píšete kromě kódu, abyste pomohli někomu jinému pochopit, jak to funguje. Možná o tom takhle nepřemýšlíte, ale dobrým příkladem dokumentace kódu je soubor README. Dobrým příkladem základní dokumentace je Express.soubor JS README. Odpovídá na několik důležitých otázek týkajících se rámce a řekne vám, jak jej můžete zahrnout do svého projektu, jak jej nainstalovat a jak spouštět testy.
dobrá dokumentace může přijít také ve formě dokumentace API. Ještě jednou, vyjádřit.js poskytuje skvělý příklad. Tato verze dokumentace je spíše referenční knihovnou pro vývojáře používající rámec. Najdete zde odpovědi na otázky, co jednotlivé funkce dělají a co znamenají různé parametry těchto funkcí. Bez této kvalitní dokumentace by Express neměl tolik týmů, které by ji používaly jako oni.
a samozřejmě můžete použít i in-line komentáře k dokumentu. Tyto druhy komentářů se obvykle nepoužívají k učení lidí mimo váš vlastní tým o kódu. Místo toho jsou užitečné vysvětlit, co se děje v určitém kousku kódu vašim spoluhráčům nebo vašemu budoucímu já.
proč byste měli dokumentovat svůj kód
jak je uvedeno výše, mnoho vývojářů nerozumí účelu dokumentace kódu. Budou tvrdit, že dobrý kód by měl být samodokumentační a že byste ho neměli muset vysvětlovat. Tito lidé se jedním slovem mýlí. Pravdou je, že dobrá dokumentace je nezbytnou součástí jakékoli kódové základny. Proč? Protože lidé by neměli potřebovat číst celý váš kód, aby pochopili, co dělá. “Lidé” v této předchozí větě mohou odkazovat na kohokoli, včetně vašeho budoucího já.
pravdou je, že často “lidé”, kteří budou muset pochopit kód poté, co je napsán, jste vy. Ta trocha logiky, která se zdála tak chytrá, když jste ji psali před šesti měsíci, může být dnes těžko pochopitelná. Pokud je váš kód dobře zdokumentován, nemusíte trávit čas snahou pochopit, co dělá. Budete moci strávit několik sekund při pohledu na popis a pak se vrátit k tomu, na čem právě pracujete.
pokud máte to štěstí, že pracujete na kódu, který používají desítky nebo stovky vývojářů, dobrá dokumentace je ještě důležitější. Životy vašich uživatelů se výrazně zlepší váš čas strávený psaním dobré dokumentace, a oni vám za to poděkují. Doslova!
klíčem k zapamatování je, že dobrá dokumentace šetří více času, než je potřeba k napsání. To může být váš čas, nebo to může být čas členů týmu, nebo dokonce i lidé, budete nikdy setkat. Někdy vám psaní dokumentace dokonce pomůže rozpoznat část kódu, která je příliš komplikovaná, takže ji můžete zjednodušit.
některé běžné chyby v dokumentaci
jako junior developer budete muset trávit čas učením, co dělá dokumentaci efektivní. Dobrou zprávou je, že se můžete učit od lidí, kteří odešli před vámi, abyste se vyhnuli běžným chybám.
Poddokumentace
jednou častou chybou, kterou vidím v dokumentaci kódu, je dokumentovat informace, které jsou již jasně viditelné. Například, líný vývojáři přidat “dokumentace” funkce tím, že přidá blok, který obsahuje název funkce, stejně jako názvy jednotlivých parametrů a jejich jednotlivých typů. Tento typ dokumentace je k ničemu! Trvá několik sekund, než si někdo přečte název funkce a parametry, které vyžaduje. To není dokumentace, je to jen opakování. Místo toho by dokumentace měla obsahovat rychlou informaci o tom, co funkce dělá a jak každý parametr mění chování funkce nebo proč je potřeba.
nadměrná dokumentace
opačný vzor může být také vážným problémem. Aby se zabránilo psaní příliš málo dokumentace, někteří vývojáři chtěli napsat vysvětlení pro každý malý kousek logiky, která je obsažena ve funkci. Pečlivě dokumentují každé zdůvodnění, které šlo do vytvoření funkce. V době, kdy jsou hotovi, možná strávili tak dlouho psaním funkce jako psaním dokumentace. Co je horší, dokumentace je často obtížné pochopit a trvá stejně dlouho jako čtení kódu. Taková dokumentace je také ztráta času. Namísto, dobrá dokumentace poskytuje základní vysvětlení toho, co a proč. Pokud existují nějaké obzvláště složité části kódu, které je třeba pochopit, pak by dokumentace měla vysvětlovat právě tyto části.
spoléhání se na testy pro dokumentaci
občas narazíte na někoho, kdo tvrdí, že nejlepší formou dokumentace jsou testy jednotek. Tento přístup má hlavní nedostatek: testy čtecí jednotky jsou často stejně obtížné jako samotné čtení kódu. Každý vývojář, který se chce dozvědět, co váš kód dělá, bude mít velký první krok, zatímco bude lovit a číst všechny vaše testy jednotek. Mnozí se prostě vzdají, než dosáhnou toho, co se rozhodli udělat. Zatímco testování jednotek je cenným doplňkem jakékoli kódové základny, není to náhrada za dobrou dokumentaci.
Způsoby, jak Vzít Dokumentaci na Další Úroveň,
Pokud pracujete na velké základní kód, kód dokumentace může cítit skličující, zvláště pokud jste nebyli pilní o dokumentování kódu až do tohoto bodu. Může to mít pocit, že se snažíte vařit oceán. Pokud máte velkou kódovou základnu, nebo ten, kde víte, že dobrá dokumentace je kritická, možná budete chtít prozkoumat nástroje pro automatickou dokumentaci kódu. Tyto nástroje drasticky zjednodušují proces psaní konzistentní, dobrá dokumentace pro celý tým. Nástroj, jako GhostDoc bude inteligentně se podívejte na kódu a použít šablony zjištěno, váš tým na kick-start své dokumentace s pár stisknutí tlačítek. Automatizované dokumentační nástroje odstraňují jeden z dalších běžných důvodů, proč se postavit proti psaní dokumentace: trvá to příliš mnoho času.
jakmile budete mít konzistentní dokumentaci, další nástroje vám umožní snadno sdílet tuto dokumentaci. Automatizované nástroje pro dokumentaci odstraňují bolest z vývoje dobré dokumentace pro věci, jako jsou veřejná rozhraní API, která váš kód poskytuje.
Začněte ještě dnes
psaní skvělé dokumentace je mnohem jednodušší než psaní kódu. Na rozdíl od kódu není dokumentace podnikem typu vše nebo nic. Začněte s cílem psát dobrou dokumentaci pro jednu funkci každý den. Tento druh praxe buduje zdravé návyky, a uvidíte výplatu po silnici, když strávíte mnohem méně času snahou porozumět částem vaší kódové základny. Postupem času se začne cítit špatně, když píšete kód, který nemá dobrou dokumentaci. Během kontroly kódu začnete upozorňovat na způsoby, jak vylepšit dokumentaci svým spolupracovníkům. Jeden malý zvyk zlepší kód vašeho týmu pro celé vaše podnikání.
zjistěte, jak může GhostDoc pomoci zjednodušit vaše komentáře XML, vytvářet a udržovat dokumentaci nápovědy kvality.
O autorovi
Eric Boersma
Eric Boersma je softwarový vývojář a manažer rozvoje, který dělá vše od bezpečnosti IT ve farmaceutickém průmyslu pro psaní inteligence software pro vládu USA k budování mezinárodní rozvoj týmů pro non-zisky. Rád mluví o věcech, které se během cesty naučil, a rád poslouchá a učí se také od ostatních.
