A kóddokumentációs eszközökre nagy szükség van, mivel segítenek dokumentálni a kódot. A kóddokumentáció egy olyan folyamat, amelynek során a programozó dokumentálja a kódját. Ez egy jól ismert kifejezés a mérnökök körében.
Sok programozót látszólag zavarba ejt a kóddokumentáció, és igyekszik minél jobban kitérni előle. A kóddokumentáció megírásának céltalansága a kód rossz olvashatóságához és a csapat többi tagjának nehéz karbantartásához vezet.
A kóddokumentáció különbözik a projektdokumentációtól, mivel elsősorban arra irányul, hogyan működik a rendszer. Bár a kóddokumentáció írásának több oka is van, sok programozó hajlamos kihagyni azt. Ha Ön is azok közé a programozók közé tartozik, akik nem dokumentálják a kódjukat, nézze meg, miért érdemes dokumentációt írnia!
-
- Egy idő után visszatér a kódjához! Jobb most megírni a kód dokumentációját, mint később megbánni.
-
- Azt akarod, hogy a kódodat a csapat többi programozója is karbantartja és használja. A kód karbantartása nagy problémává válik, ha nincs dokumentálva.
-
- Szükséged van arra, hogy mások segítsenek neked nyílt forráskódú és egyéb együttműködések révén. Ha azon gondolkodsz, hogy nagyszabású és kollaboratív munkát vállalsz, kezdd el most dokumentálni a kódodat!
-
- Jobb kódolóvá akarsz válni! A kódod dokumentálása sokkal érthetőbbé
teszi számodra a logikát. A kóddokumentáció írásának szokása a kódodat is jobbá teszi.
- Jobb kódolóvá akarsz válni! A kódod dokumentálása sokkal érthetőbbé
- A kóddokumentáció írása javítja az írói képességeidet.
Még a fenti előnyök mellett is a dokumentálás összességében időigényes folyamat. A gyorsabb dokumentálási folyamat és a stílusbeli konzisztencia érdekében érdemes kóddokumentációs eszközöket használni.
Az eszközök jobb dokumentálóvá és remek kódolóvá teszik Önt! Kezdjünk bele.
1. LiveEdu
Ha ezt olvasod, biztosan azon gondolkodsz, hogyan lehet egy közösségi projektközvetítés a kóddokumentáció eszköze? A válasz a következő kifejezésben rejlik: “Videó kóddokumentáció.”
A projektmunkáját közvetlenül a Livecodingon közvetítheti vagy tárolhatja. Ezzel könnyedén hozzáférést biztosíthat a csapattagoknak a projekt fontos részeihez. Több előnye is van annak, ha a Livecodingot eszközként használja a kód dokumentálásához. Ezek közül néhányat az alábbiakban említünk:
A videodokumentáció előnyei dióhéjban
-
- Javítja a tisztán szöveges dokumentációt, és jobb kontextust és megértést biztosít az olvasó számára.
-
- Az agilis csapatok könnyen nyomon követhetik a projektváltozásokat.
-
- A technikai írók a videokóddokumentációt felhasználhatják a projekt jobb megértéséhez.
- A fejlesztők a megtakarított időt a projekt egyéb funkcióinak megvalósítására fordíthatják.
Az ötlet jobb megértéséhez olvassa el a Damian Wolf által írt “Why Developers Write Horrible Documentation and How to Solve It” című epikus írást.
Doxygen
A Doxygen egy nagyszerű eszköz a dokumentáció forráskódból történő generálására. Az eszköz célja a C++, de PHP, Java, Python stb. esetén is használható. A Doxygen segítségével online HTML dokumentációt készíthetünk. Emellett többféle formátumú kimenet generálására is használható, beleértve a Unix man oldalakat, PostScriptet stb.
A Doxygen használatának legnagyobb előnye, hogy a forráskód dokumentációja konzisztens lesz. Segítségével kódszerkezetet is generálhat a dokumentálatlan forrásfájlok felhasználásával. Mindössze annyit kell tennie, hogy ennek megfelelően konfigurálja.
Edurolp, a spanyolországi Córdobából a Doxygen segítségével dokumentálja a kódját! Nézd meg a streamet itt.
Sphinx
A Sphinx egy népszerű dokumentációs eszköz a programozók számára. BSD licenc alatt érhető el, és több programozási nyelvet támogat, mint például a Python, C és C++. A Sphinx ideális a dokumentációjukat rendszerezni kívánó fejlesztők számára. Mind a projektdokumentációhoz, mind a kóddokumentációhoz használható. A Sphinx néhány jellemzője a kiterjedt kereszthivatkozások, a többféle kimeneti formátum, az automatikus indexek, a kiterjesztések támogatása stb.
4. Pandoc
A Pandoc nem olyan, mint a többi kóddokumentációs eszköz. Svájci bicskaként működik, és lehetővé teszi a fejlesztő számára, hogy gyorsan átalakítson egy jelölési formátumot egy másikra. Ha szereted a saját kóddokumentációdat markupban írni, és gyorsan át akarod konvertálni egy másik formátumba, a Pandoc neked való. Széles körű dokumentumtámogatással rendelkezik, beleértve a textilt, a reStrcuturedTextet, a LaTexet, az ePUB-ot stb.
Mellett számos markdown szintaxis-kiterjesztést kínál, beleértve a definíciós listákat, táblázatokat, lábjegyzeteket stb. is. A támogatott kiterjesztések és dokumentumformátumok teljes listáját a hivatalos oldalon találja.
5. Dr. Explain
A frontend fejlesztés bizonyos mértékig dokumentációt is igényel. Az egyik ilyen eszköz, a Dr. Explain lehetővé teszi az alkalmazás felhasználói felületének dokumentálását. Kiszűri a legfontosabb felületelemeket, majd kivonja az egyes elemekhez tartozó metainformációkat. Ha ez megtörtént, a kinyert információkat módosíthatja, hogy gyorsan elkészíthesse a felhasználói felület dokumentációját.
6. LaTex
A LaTex a tudományos projektek dokumentálásának defacto szabványa. Azonban más típusú projektekhez is felhasználható, beleértve a kód- és projektdokumentációt is. Egy ilyen felhasználó, dcelisgarza a mexikói Monterreryből mutatja be a LaTex hasznosságát a matematikai kód dokumentálásában. Nézze meg itt!
A LaTex jól ismert, mint kiváló minőségű, tudományos és műszaki dokumentáció készítésére összpontosító szedőrendszer.
7. Markdown
A John Gruber által létrehozott Markdown egy egyszerű nyelv, amely segít a kiváló minőségű kód és projektdokumentáció írásában. Gyakorlatilag a Markdown egy szövegből HTML-é alakító eszköz webes írók számára, de ugyanúgy használható dokumentációs célokra is. Fejlesztőként megírhatja a dokumentációt Markdownban, és később a Pandoc segítségével bármilyen formátumba konvertálhatja azt!
Nézze meg AbiAbdallahAwad használatát Markdown segítségével API-k dokumentálására RAML-ben itt.
8. GhostDoc
A GhostDoc, egy Visual Studio-bővítmény segítségével könnyedén generálhatsz XML-dokumentum-kommentárokat. Az eszköz több tényező, például a név, a paraméterek, a kontextuális információk, a típus stb. alapján generálja a megjegyzéseket.
9. Natural Docs
A Natural Docs egy újabb nyílt forráskódú dokumentumgenerátor, amely számos programozási nyelvvel működik. Segít a kóddokumentáció generálásának automatizálásában és HTML formátumba konvertálásában. Jelenleg a natural docs 19 nyelvet támogat, köztük Python, C++, PL/SQL, Actionscript stb.
10. phpDocumentor
Ha PHP-fejlesztő vagy, és szeretnél kóddokumentációt generálni a forráskódból, ne keress tovább a phpDocumentornál. A phpDocumentor egyedülálló módon kezeli a kóddokumentációt, és referenciaként szolgál a megfelelő dokumentációhoz. A phpDocumentor legfontosabb jellemzői a PHP keretrendszerek támogatása, a pluggable architektúra stb. A belső munkát egy erős és rugalmas sablonrendszer kezeli. Az eszköz segítségével jelentéseket és grafikonokat is készíthet, és javíthatja a kód általános minőségét.
Bónusz: A Doc-O-Matic egy fizetős szoftver a kóddokumentáció létrehozására. Tudjon meg róla többet itt.
Következtetés
A mai napon 10 eszközt tekintettünk át a tökéletes kóddokumentációhoz. Meg kell jegyezni, hogy a fent említett eszközök a dokumentációs folyamat kiegészítéseként működnek. A megfelelő dokumentációra továbbra is szükség van, és nem szabad figyelmen kívül hagyni.