Værktøjer til kodedokumentation er et must for tiden, da de hjælper med at dokumentere din kode. Kodedokumentation er en proces, hvormed en programmør dokumenterer sin kode. Det er et velkendt begreb blandt ingeniører.
Mange programmører synes at være forvirrede over kodedokumentation og forsøger at undvige den så meget som muligt. Det manglende formål med at skrive kodedokumentation fører til dårlig læsbarhed af koden og vanskelig vedligeholdelse for andre teammedlemmer.
Kodedokumentation adskiller sig fra projektdokumentation, da den primært sigter på, hvordan systemet fungerer. Selv om der er flere grunde til at skrive kodedokumentation, har mange programmører en tendens til at springe dem over. Hvis du er en af de programmører, der ikke dokumenterer deres kode, så tjek de grunde, du bør skrive docs!
-
-
- Du kommer tilbage til din kode efter noget tid! Det er bedre at skrive kodedokumentation nu end at fortryde senere.
-
- Du ønsker, at din kode skal vedligeholdes og bruges af andre programmører i teamet. Vedligeholdelse af koden bliver et stort problem, hvis den ikke er dokumenteret.
-
- Du har brug for andre til at hjælpe dig gennem open source og andre samarbejder. Hvis du overvejer at gå i stor stil og samarbejde, så begynd at dokumentere din kode nu!
-
- Du ønsker at blive en bedre koder! Hvis du dokumenterer din kode, bliver logikken
meget mere klar for dig. Vanen med at skrive kodedokumentation gør også din kode bedre.
- Du ønsker at blive en bedre koder! Hvis du dokumenterer din kode, bliver logikken
- Skrivning af kodedokumentation forbedrer dine skriveevner.
Selv med alle de ovennævnte fordele er dokumentation i det store og hele en tidskrævende proces. For at muliggøre en hurtigere dokumentationsproces og stilkonsistens bør du bruge kodedokumentationsværktøjer.
Værktøjerne vil gøre dig til en bedre dokumentarist og en fantastisk koder! Lad os komme i gang.
1. LiveEdu
Hvis du læser dette, tænker du sikkert, hvordan en social projektudsendelse kan være et værktøj til kodedokumentation? Svaret ligger i begrebet “Videokodedokumentation.”
Du kan udsende eller gemme dit projektarbejde direkte på Livecoding. Ved at gøre dette vil du nemt kunne give dine teammedlemmer adgang til vigtige dele af projektet. Der er flere fordele ved at bruge Livecoding som et værktøj til at dokumentere din kode. Nogle af dem er nævnt nedenfor:
Videodokumentationsfordele i en nøddeskal
-
- Det forbedrer ren tekstskrevet dokumentation og giver bedre sammenhæng og forståelse for læseren.
-
- Agile teams kan nemt holde styr på projektets ændringer.
-
-
- Tekniske skribenter kan bruge videokodedokumentationen til at forstå projektet bedre.
- Udviklerne kan investere deres sparede tid i at implementere andre projektfunktionaliteter.
Læs det episke stykke skrevet af Damian Wolf, “Why Developers Write Horrible Documentation and How to Solve It”, for at forstå ideen bedre.
Doxygen
Doxygen er et fantastisk værktøj til at generere dokumentation fra kildekode. Værktøjet er rettet mod C++, men det kan også bruges med PHP, Java, Python osv. Ved hjælp af Doxygen kan du oprette online HTML-dokumentation. Det kan også bruges til at generere output i flere forskellige formater, herunder Unix man pages, PostScript osv.
Den største fordel ved at bruge Doxygen er, at du vil få konsistens i hele din kildekodedokumentation. Det kan også hjælpe dig med at generere kodestruktur ved hjælp af de udokumenterede kildefiler. Det eneste du skal gøre er at konfigurere det i overensstemmelse hermed.
Edurolp fra Córdoba, Spanien bruger Doxygen til at dokumentere sin kode! Se streamet her.
Sphinx
Sphinx er et populært dokumentationsværktøj for programmører. Det er tilgængeligt under BSD-licens og understøtter flere programmeringssprog såsom Python, C og C++. Sphinx er ideel til udviklere, der ønsker at organisere deres dokumentation. Det kan bruges til både projektdokumentation og kodedokumentation. Nogle af funktionerne i Sphinx omfatter omfattende krydsreferencer, flere outputformater, automatiske indekser, understøttelse af udvidelser osv.
4. Pandoc
Pandoc er ikke som andre kodedokumentationsværktøjer derude. Det fungerer som en schweizerkniv og gør det muligt for en udvikler hurtigt at konvertere et markup-format til et andet. Hvis du kan lide at skrive din egen kodedokumentation i markup, og hurtigt ønsker at konvertere til et andet format, er Pandoc noget for dig. Det har en bred vifte af dokumentunderstøttelse, herunder tekstil, reStrcuturedText, LaTex, ePUB osv.
Dertil kommer, at det tilbyder flere markdown-syntaksudvidelser, herunder definitionslister, tabeller, fodnoter osv. Tjek den officielle side for en komplet liste over understøttede udvidelser og dokumentformat.
5. Dr. Forklar
Frontend-udvikling kræver også dokumentation i en vis udstrækning. Et sådant værktøj, Dr. Explain, giver dig mulighed for at dokumentere app-brugergrænsefladen. Det filtrerer de vigtigste grænsefladeelementer ud og udtrækker derefter de tilknyttede metaoplysninger om hvert element. Når det er gjort, kan du ændre de ekstraherede oplysninger for hurtigt at oprette en grænsefladedokumentation.
6. LaTex
LaTex er den defacto standard for dokumentation af videnskabelige projekter. Det kan dog også bruges til andre typer projekter, herunder kode- og projektdokumentation. En af disse brugere, dcelisgarza fra Monterrery i Mexico, viser, hvor nyttigt LaTex er i matematisk kodedokumentation. Tjek det ud her!
LaTex er velkendt som et sættesystem af høj kvalitet med fokus på produktion af videnskabelig og teknisk dokumentation.
7. Markdown
Markdown, en skabelse af John Gruber, er et simpelt sprog, der hjælper dig med at skrive kode og projektdokumentation af høj kvalitet. Teknisk set er Markdown et tekst-til-HTML-værktøj til webskribenter, men det er kan lige så godt bruges til dokumentationsformål. Som udvikler kan du skrive dokumentationen i Markdown og senere bruge Pandoc til at konvertere den til et hvilket som helst format du ønsker!
Se AbiAbdallahAwad bruge Markdown til at dokumentere API’er i RAML her.
8. GhostDoc
Med GhostDoc, en udvidelse til Visual Studio, kan du nemt generere dine XML-dokumentkommentarer. Værktøjet genererer kommentarer baseret på flere faktorer, herunder navn, parametre, kontekstuelle oplysninger, type osv.
9. Natural Docs
Natural Docs er endnu en open source-dokumentgenerator, der fungerer med mange programmeringssprog. Den hjælper dig med at automatisere generering af kodedokumentation og konvertere den til HTML-format. I øjeblikket understøtter natural docs 19 sprog, herunder Python, C++, PL/SQL, Actionscript osv.
10. phpDocumentor
Hvis du er PHP-udvikler og ønsker at generere kodedokumentation fra kildekoden, skal du ikke lede længere end phpDocumentor. phpDocumentor er en unik måde at håndtere din kodedokumentation på og fungerer som en reference til korrekt dokumentation. Nøglefunktioner i phpDocumentor er PHP framework support, pluggable arkitektur, osv. Indvendigt arbejde styres af et kraftfuldt og fleksibelt skabelonsystem. Værktøjet kan også hjælpe dig med at generere rapporter og grafer og forbedre den overordnede kodekvalitet.
Bonus: Doc-O-Matic er en betalt software til generering af kodedokumentation. Få mere at vide om det her.
Konklusion
I dag gennemgik vi 10 værktøjer til perfekt kodedokumentation. Det skal bemærkes, at de nævnte værktøjer fungerer som supplementer til din dokumentationsproces. Korrekt dokumentation er stadig nødvendig, og bør ikke ignoreres.