Education Ecosystem Blog

Verktyg för koddokumentation är ett behov för stunden eftersom de hjälper dig att dokumentera din kod. Koddokumentation är en process genom vilken en programmerare dokumenterar sin kod. Det är en välkänd term bland ingenjörer.

Många programmerare verkar vara förbryllade av koddokumentation och försöker undvika den så mycket som möjligt. Bristen på syfte att skriva koddokumentation leder till dålig läsbarhet av koden och svårt underhåll för andra teammedlemmar.

Koddokumentation skiljer sig från projektdokumentation eftersom den främst syftar till hur systemet fungerar. Även om det finns flera anledningar till att skriva koddokumentation tenderar många programmerare att hoppa över dem. Om du är en av de kodare som inte dokumenterar sin kod, kolla in orsakerna till varför du bör skriva docs!

• • Du kommer tillbaka till din kod efter en tid! Det är bättre att skriva koddokumentation nu än att ångra sig senare.

• • Du vill att din kod ska underhållas och användas av andra programmerare i teamet. Underhåll av koden blir ett stort problem om den inte är dokumenterad.

• • Du behöver andra som hjälper dig genom öppen källkod och andra samarbeten. Om du funderar på att satsa stort och samarbeta, börja dokumentera din kod nu!

• • Du vill bli en bättre kodare! Att dokumentera din kod gör logiken
    mycket tydligare för dig. Vanan att skriva koddokumentation gör också din kod bättre.

• Att skriva koddokumentation förbättrar din skrivförmåga.

Även med alla ovanstående fördelar är dokumentation på det hela taget en tidskrävande process. För att möjliggöra en snabbare dokumentationsprocess och en konsekvent stil bör du använda koddokumentationsverktyg.

Verktygen kommer att göra dig till en bättre dokumentatör och en fantastisk kodare! Låt oss komma igång.

1. LiveEdu

Om du läser det här måste du fundera på hur en sändning av ett socialt projekt kan vara ett verktyg för koddokumentation? Svaret ligger i begreppet ”Videokoddokumentation”
Du kan sända eller lagra ditt projektarbete direkt på Livecoding. Genom att göra detta kan du enkelt ge dina teammedlemmar tillgång till viktiga delar av projektet. Det finns flera fördelar med att använda Livecoding som ett verktyg för att dokumentera din kod. Några av dem nämns nedan:

Fördelar med videodokumentation i ett nötskal

1. 1. Det förbättrar ren textdokumentation och ger bättre sammanhang och förståelse för läsaren.

1. 1. Agila team kan enkelt hålla koll på projektändringar.

1. 1. Tekniska skribenter kan använda videokoddokumentationen för att förstå projektet bättre.

1. Utvecklare kan investera den sparade tiden i att implementera andra projektfunktioner.

Läs den episka artikeln skriven av Damian Wolf, ”Why Developers Write Horrible Documentation and How to Solve It”, för att förstå idén bättre.

Doxygen

Doxygen är ett utmärkt verktyg för att generera dokumentation från källkod. Verktyget är inriktat på C++, men kan även användas med PHP, Java, Python osv. Med hjälp av Doxygen kan du skapa HTML-dokumentation online. Det kan också användas för att generera utdata i flera olika format, inklusive Unix man pages, PostScript etc.

Den största fördelen med att använda Doxygen är att du kommer att få konsistens i hela din källkodsdokumentation. Det kan också hjälpa dig att generera kodstruktur med hjälp av de odokumenterade källfilerna. Allt du behöver göra är att konfigurera den därefter.

Edurolp, från Córdoba, Spanien använder Doxygen för att dokumentera sin kod! Kolla in strömmen här.

Sphinx

Sphinx är ett populärt dokumentationsverktyg för programmerare. Det är tillgängligt under BSD-licens och stöder flera programmeringsspråk som Python, C och C++. Sphinx är idealiskt för utvecklare som vill organisera sin dokumentation. Det kan användas för både projektdokumentation och koddokumentation. Några funktioner i Sphinx är omfattande korsreferenser, flera utdataformat, automatiska index, stöd för tillägg osv.

4. Pandoc

Pandoc är inte som andra koddokumentationsverktyg där ute. Det fungerar som en schweizisk armékniv och gör det möjligt för en utvecklare att snabbt konvertera ett markeringsformat till ett annat. Om du gillar att skriva din egen koddokumentation i markup och snabbt vill konvertera till ett annat format är Pandoc något för dig. Det har ett brett utbud av dokumentstöd, inklusive textil, reStrcuturedText, LaTex, ePUB, etc.

Det erbjuder dessutom flera markdown-syntaxförlängningar, inklusive definitionslistor, tabeller, fotnoter, etc. Kolla in den officiella sidan för en fullständig lista över stödda tillägg och dokumentformat.

5. Dr Explain

Frontendutveckling kräver också dokumentation i viss utsträckning. Ett sådant verktyg, Dr. Explain, låter dig dokumentera appens användargränssnitt. Det filtrerar ut de viktigaste gränssnittselementen och extraherar sedan den tillhörande metainformationen om varje element. När det är gjort kan du ändra den extraherade informationen för att snabbt skapa en gränssnittsdokumentation.

6. LaTex

LaTex är en defacto standard för dokumentation av vetenskapliga projekt. Den kan dock även användas för andra typer av projekt, inklusive kod- och projektdokumentation. En sådan användare, dcelisgarza från Monterrery i Mexiko, visar hur användbar LaTex är för dokumentation av matematisk kod. Kolla in det här!

LaTex är välkänt som ett högkvalitativt sättningssystem med fokus på att producera vetenskaplig och teknisk dokumentation.

7. Markdown

Markdown, en skapelse av John Gruber, är ett enkelt språk som hjälper dig att skriva kod och projektdokumentation av hög kvalitet. Tekniskt sett är Markdown ett text-till-HTML-verktyg för webbskribenter, men det kan lika gärna användas för dokumentationsändamål. Som utvecklare kan du skriva dokumentationen i Markdown och senare använda Pandoc för att konvertera den till vilket format du vill!

Kolla in AbiAbdallahAwad som använder Markdown för att dokumentera API:er i RAML här.

8. GhostDoc

Med GhostDoc, ett tillägg till Visual Studio, kan du enkelt generera kommentarer till dina XML-dokument. Verktyget genererar kommentarer baserat på flera faktorer, inklusive namn, parametrar, kontextuell information, typ osv.

9. Natural Docs

Natural Docs är ännu en dokumentgenerator med öppen källkod som fungerar med många programmeringsspråk. Den hjälper dig att automatisera generering av koddokumentation och konvertera den till HTML-format. För närvarande stöder natural docs 19 språk inklusive Python, C++, PL/SQL, Actionscript etc.

10. phpDocumentor

Om du är en PHP-utvecklare och vill generera koddokumentation från källkoden, behöver du inte leta längre än till phpDocumentor. phpDocumentor är ett unikt sätt att hantera din koddokumentation och fungerar som en referens till korrekt dokumentation. Viktiga funktioner i phpDocumentor är stöd för PHP-ramverk, pluggable arkitektur osv. Inre jobbet hanteras av ett kraftfullt och flexibelt mallsystem. Verktyget kan också hjälpa dig att generera rapporter och grafer och förbättra den övergripande kodkvaliteten.

Bonus: Doc-O-Matic är en betald programvara för att generera koddokumentation. Läs mer om den här.

Slutsats

I dag gick vi igenom 10 verktyg för perfekt koddokumentation. Det bör noteras att verktygen som nämns ovan fungerar som tillägg till din dokumentationsprocess. Korrekt dokumentation krävs fortfarande och bör inte ignoreras.