Code Documentation: The Complete Beginner’ s Guide
már kezded az első programozási munkát, és a dolgok egyre könnyebbé válnak. Először az összes kód, amivel foglalkoznod kellett, talán túlterhelt és összezavart téged, de kezdesz belejönni. Ez nagyszerű! Most azon tűnődsz, hogyan lehet a kódot a következő szintre vinni. Bár sok mindent meg kell tanulni a programozási veremről, amelyek közül sok jobb programozóvá tesz téged, van néhány, amely kiszolgálja Önt, függetlenül attól, hogy milyen veremben dolgozik. Az egyik ilyen a kóddokumentáció.
sok fejlesztő nem ír elegendő dokumentációt, vagy azért, mert nem látja az értéket, vagy mert úgy érzi, hogy nincs ideje. Nem kell, hogy az egyik ilyen Fejlesztők. Egy kis idő és sok gyakorlat, akkor adjunk hozzá dokumentációt a kódot, ami olvasás öröm használni mind az Ön és bárki más, aki jön.
A jó dokumentáció sokféle formában létezik
amikor a legtöbb fejlesztő a kóddokumentációra gondol, akkor a megjegyzésekre gondol. A Megjegyzések értékes kiegészítések lehetnek a kódhoz, de nem csak a dokumentáció meghatározása. A dokumentáció bármi, amit a kód mellett ír, hogy segítsen valaki másnak megérteni, hogyan működik. Lehet, hogy nem így gondolja, de a kóddokumentáció jó példája a README fájl. Az alapvető dokumentáció jó példája az Express.js README fájl. Számos fontos kérdésre ad választ a keretrendszerrel kapcsolatban, és elmondja, hogyan vonhatja be a projektbe, hogyan telepítheti, és hogyan futtathatja a teszteket.
a jó dokumentáció API dokumentáció formájában is elérhető. Még egyszer, expressz.a js nagyszerű példát mutat. A dokumentáció ezen verziója inkább referencia könyvtár a keretrendszert használó fejlesztők számára. Választ talál arra a kérdésre, hogy az egyes függvények mit jelentenek, és mit jelentenek a függvények különböző paraméterei. E minőségi dokumentáció nélkül az Expressnek közel annyi csapata nem használná, mint ők.
és természetesen az in-line megjegyzéseket is használhatja a kód dokumentálásához. Az ilyen jellegű megjegyzéseket általában nem arra használják, hogy a saját csapatán kívüli embereket megtanítsák a kódról. Helyette, hasznosak, hogy elmagyarázzák, mi történik egy adott kódrészletben csapattársainak vagy jövőbeli önmagának.
miért kell dokumentálnia a kódját
mint fentebb megjegyeztük, sok fejlesztő nem érti a kóddokumentáció célját. Azt állítják, hogy a jó kódnak öndokumentálónak kell lennie, és nem kell magyaráznia. Ezek az emberek egy szóval tévednek. Az igazság az, hogy a jó Dokumentáció minden kódbázis elengedhetetlen része. Miért? Mert az embereknek nem kell elolvasniuk az összes kódot, hogy megértsék, mit csinál. Az előző mondatban szereplő” emberek ” bárkire utalhatnak, beleértve a jövőbeli énedet is.
az igazság az, hogy gyakran az “emberek”, akiknek meg kell érteniük a kódot, miután megírták, te vagy. Ezt a kis logikát, amely olyan okosnak tűnt, amikor hat hónappal ezelőtt írta, ma nehéz lehet megérteni. Ha a kód jól dokumentált, akkor nem kell időt töltenie azzal, hogy megértse, mit csinál. Néhány másodpercet eltölthet a leírás megtekintésével, majd visszatérhet arra, amin éppen dolgozik.
ha olyan szerencsés vagy, hogy több tucat vagy több száz fejlesztő által használt kódon dolgozol, a jó dokumentáció még fontosabb. A felhasználók életét jelentősen javítja a jó dokumentáció írásával töltött idő, és köszönetet fognak mondani érte. Szó szerint!
a legfontosabb megjegyezni, hogy a jó dokumentáció több időt takarít meg, mint amennyi az íráshoz szükséges. Lehet, hogy a te időd, vagy a csapattagok ideje, vagy akár olyan emberek, akikkel soha nem fogsz találkozni. Néha a dokumentáció írása még a kód túl bonyolult részének felismerésében is segít, így egyszerűsítheti azt.
néhány gyakori Dokumentációs hiba
junior fejlesztőként időt kell fordítania arra, hogy megtanulja, mi teszi a dokumentációt hatékonyvá. A jó hír az, hogy tanulhat olyan emberektől, akik előtted jártak, így elkerülheti a gyakori hibákat.
Under-Documentation
az egyik gyakori hiba, amit a kóddokumentációnál látok, a már jól látható információk dokumentálása. Például a lusta Fejlesztők hozzáadnak egy” dokumentációt ” egy függvényhez egy blokk hozzáadásával, amely megadja a függvény nevét, valamint az egyes paraméterek nevét és az egyes típusokat. Ez a fajta dokumentáció haszontalan! Másodpercekbe telik, amíg valaki elolvassa a függvény nevét és a szükséges paramétereket. Ez nem dokumentáció, csak ismétlés. Ehelyett a dokumentációnak tartalmaznia kell egy rövid információt arról, hogy a függvény mit csinál, és hogyan változtatja meg az egyes paraméterek a függvény viselkedését, vagy miért van rá szükség.
Túldokumentáció
az ellenkező minta is komoly problémát jelenthet. Annak elkerülése érdekében, hogy túl kevés dokumentációt írjon, egyes fejlesztők szeretik leírni a magyarázatot minden apró logikára, amelyet egy függvény tartalmaz. Aprólékosan dokumentálják a függvény létrehozásának minden indoklását. Mire elkészülnek, lehet, hogy annyi időt töltöttek a funkció megírásával, mint a dokumentáció megírásával. Ami még rosszabb, a dokumentációt gyakran nehéz megérteni, és csak annyi időt vesz igénybe, mint a kód elolvasása. Ez a fajta dokumentáció is időpocsékolás. Ehelyett a jó dokumentáció alapvető magyarázatot ad mind a mi, mind a miért. Ha a kódnak vannak különösen trükkös részei, amelyeket meg kell érteni, akkor a dokumentációnak csak ezeket a részeket kell megmagyaráznia.
tesztekre támaszkodva dokumentálni
alkalmanként összefut valakivel, aki azt állítja, hogy a dokumentáció legjobb formája az egységteszt. Ennek a megközelítésnek van egy jelentős hiányossága: az egységtesztek olvasása gyakran ugyanolyan nehéz, mint maga a kód olvasása. Bármely fejlesztő, aki meg akarja tanulni, mit csinál a kódod, nagy első lépést fog tenni, miközben vadászik és elolvassa az összes egység tesztet. Sokan csak feladják, mielőtt elérnék azt,amit kitűztek. Míg az egységtesztelés értékes kiegészítő minden kódbázishoz, ez nem helyettesíti a jó dokumentációt.
A dokumentáció következő szintre emelésének módjai
ha nagy kódbázison dolgozik, a kóddokumentáció ijesztőnek érezheti magát, különösen, ha eddig nem volt szorgalmas a kód dokumentálásában. Olyan érzés lehet, mintha az óceánt próbálnád felforralni. Ha nagy kódbázisa van, vagy olyan, ahol tudja, hogy a jó dokumentáció kritikus, érdemes megvizsgálni az automatizált kóddokumentációs eszközöket. Ezek az eszközök drasztikusan leegyszerűsítik a következetes, jó dokumentáció írásának folyamatát egy egész csapat számára. Egy olyan eszköz, mint a GhostDoc, intelligensen megvizsgálja a kódot, és a csapata által létrehozott sablonokat használja a dokumentáció elindításához néhány gombnyomással. Az automatizált dokumentációs eszközök eltávolítják a dokumentáció írásának egyik leggyakoribb okát: túl sok időt vesz igénybe.
ha következetes dokumentációval rendelkezik, más eszközök lehetővé teszik a dokumentáció egyszerű megosztását. Az automatizált dokumentációs eszközök enyhítik a fájdalmat olyan dolgok jó dokumentációjának kidolgozásában, mint például a kód által biztosított nyilvános API-k.
kezdje el még ma
a nagyszerű dokumentáció írása sokkal könnyebb, mint a kód írása. A kóddal ellentétben a dokumentáció nem minden vagy semmi vállalkozás. Kezdje azzal a céllal, hogy minden nap jó dokumentációt írjon egy funkcióhoz. Ez a fajta gyakorlat egészséges szokásokat épít fel, és látni fogja a kifizetést az úton, amikor sokkal kevesebb időt töltesz a kódbázis egyes részeinek megértésével. Idővel rosszul érzi magát, amikor olyan kódot ír, amely nem rendelkezik jó dokumentációval. A kód felülvizsgálata során elkezdi rámutatni, hogyan javíthatja munkatársainak a dokumentációt. Egy kis szokás javítja a csapat kódját az egész vállalkozás számára.
Ismerje meg, hogyan segíthet a GhostDoc az XML-Megjegyzések egyszerűsítésében, a minőségi súgódokumentáció elkészítésében és karbantartásában.
A szerzőről
Eric Boersma
Eric Boersma szoftverfejlesztő és fejlesztési menedzser, aki mindent megtett a gyógyszeripar informatikai biztonságától kezdve az amerikai kormány hírszerzési Szoftvereinek írásán át a non-profit nemzetközi fejlesztési csapatok építéséig. Szeret beszélni azokról a dolgokról, amelyeket az út során megtanult, és szívesen hallgat és tanul másoktól is.
