Education Ecosystem Blog

Hulpmiddelen voor codedocumentatie zijn onmisbaar omdat ze helpen uw code te documenteren. Codedocumentatie is een proces waarbij een programmeur zijn of haar code documenteert. Het is een bekende term onder ingenieurs.

Veel programmeurs lijken verbijsterd te zijn over codedocumentatie en proberen het zoveel mogelijk te omzeilen. Het gebrek aan doel om codedocumentatie te schrijven leidt tot slechte leesbaarheid van de code en moeilijk onderhoud voor andere teamleden.

Codedocumentatie is anders dan projectdocumentatie, omdat het vooral gaat over hoe het systeem werkt. Hoewel er meerdere redenen zijn voor het schrijven van codedocumentatie, hebben veel programmeurs de neiging ze over te slaan. Als u tot de programmeurs behoort die hun code niet documenteren, bekijk dan de redenen waarom u wel documentatie zou moeten schrijven!

• • Je komt na verloop van tijd toch weer terug op je code! Het is beter om nu codedocumentatie te schrijven dan het later te berouwen.

• • U wilt dat uw code wordt onderhouden en gebruikt door andere programmeurs in het team. Het onderhoud van de code wordt een groot probleem als deze niet is gedocumenteerd.

• • U hebt anderen nodig om u te helpen via open source en andere samenwerkingsverbanden. Als je van plan bent om groots en collaboratief te werk te gaan, begin dan nu met het documenteren van je code!

• • Je wilt een betere codeur worden! Door uw code te documenteren wordt de logica
    veel duidelijker voor u. De gewoonte om codedocumentatie te schrijven maakt uw code ook beter.

• Het schrijven van codedocumentatie verbetert uw schrijfvaardigheid.

Zelfs met alle bovenstaande voordelen is documentatie, over het geheel genomen, een tijdrovend proces. Om een sneller documentatieproces en consistente stijl mogelijk te maken, zou u hulpmiddelen voor codedocumentatie moeten gebruiken.

De hulpmiddelen zullen van u een betere documenteerder en een geweldige codeur maken! Laten we beginnen.

1. LiveEdu

Als je dit leest, denk je vast hoe een sociale projectuitzending een hulpmiddel voor codedocumentatie kan zijn? Het antwoord ligt in de term, “Video code documentatie.”
U kunt uitzenden of opslaan van uw project werk rechtstreeks op Livecoding. Door dit te doen, zult u in staat om gemakkelijk uw teamleden toegang te geven tot belangrijke delen van het project. Er zijn meerdere voordelen voor het gebruik van Livecoding als een tool om uw code te documenteren. Hieronder worden er enkele genoemd:

Voordelen van videodocumentatie in een notendop

1. 1. Het verbetert pure tekstdocumentatie en geeft de lezer meer context en begrip.

1. 1. Agile-teams kunnen wijzigingen in het project gemakkelijk bijhouden.

1. 1. Technische schrijvers kunnen de videocodedocumentatie gebruiken om het project beter te begrijpen.

1. Ontwikkelaars kunnen hun bespaarde tijd investeren in de implementatie van andere projectfunctionaliteiten.

Lees het epische stuk geschreven door Damian Wolf, “Why Developers Write Horrible Documentation and How to Solve It,” om het idee beter te begrijpen.

Doxygen

Doxygen is een geweldige tool voor het genereren van documentatie uit broncode. Het gereedschap is gericht op C++, maar het kan ook worden gebruikt met PHP, Java, Python, enz. Met behulp van Doxygen kunt u online HTML documentatie maken. Het kan ook gebruikt worden om uitvoer in meerdere formaten te genereren, waaronder Unix man pages, PostScript, enz.

Het grootste voordeel van het gebruik van Doxygen is dat u consistentie krijgt in uw broncodedocumentatie. Het kan u ook helpen om code structuur te genereren met de ongedocumenteerde bronbestanden. Alles wat je hoeft te doen is het dienovereenkomstig te configureren.

Edurolp, uit Córdoba, Spanje gebruikt Doxygen om zijn code te documenteren! Bekijk de stream hier.

Sphinx

Sphinx is een populair documentatiegereedschap voor programmeurs. Het is beschikbaar onder BSD licentie en ondersteunt meerdere programmeertalen zoals Python, C, en C++. Sphinx is ideaal voor ontwikkelaars die hun documentatie willen organiseren. Het kan worden gebruikt voor zowel project documentatie als code documentatie. Enkele kenmerken van Sphinx zijn uitgebreide kruisverwijzingen, meerdere uitvoerformaten, automatische indexen, extensie-ondersteuning, enz.

4. Pandoc

Pandoc is niet zoals andere codedocumentatietools die er zijn. Het werkt als een Zwitsers zakmes en stelt een ontwikkelaar in staat om snel het ene opmaakformaat om te zetten naar een ander. Als je graag je eigen codedocumentatie in markup schrijft, en snel wilt converteren naar een ander formaat, dan is Pandoc iets voor jou. Het heeft een breed scala aan documentondersteuning, waaronder textiel, reStrcuturedText, LaTex, ePUB, enz.

Meerdere markdown syntaxis-uitbreidingen, waaronder definitielijsten, tabellen, voetnoten, enz. Kijk op de officiële pagina voor een volledige lijst van ondersteunde extensies en documentformaten.

5. Dr. Explain

Frontend ontwikkeling vereist ook documentatie tot op zekere hoogte. Met Dr. Explain kunt u de gebruikersinterface van een app documenteren. Het filtert de belangrijkste interface-elementen en extraheert vervolgens de bijbehorende meta-informatie over elk element. Eenmaal gedaan, kunt u de geëxtraheerde informatie aanpassen om snel een interface documentatie te maken.

6. LaTex

LaTex is de defacto standaard voor het documenteren van wetenschappelijke projecten. Het kan echter ook worden gebruikt voor andere soorten projecten, waaronder code- en projectdocumentatie. Een van deze gebruikers, dcelisgarza uit Monterrery, Mexico, toont het nut van LaTex voor documentatie van wiskundige code. Bekijk het hier!

LaTex staat bekend als een hoog-kwalitatief zet-systeem met een focus op het produceren van wetenschappelijke en technische documentatie.

7. Markdown

Markdown, een creatie van John Gruber, is een eenvoudige taal die u helpt bij het schrijven van hoogwaardige code en projectdocumentatie. Technisch gezien is Markdown een tekst-naar-HTML hulpmiddel voor webschrijvers, maar het kan net zo goed voor documentatiedoeleinden worden gebruikt. Als ontwikkelaar kun je de documentatie in Markdown schrijven en later Pandoc gebruiken om het in elk gewenst formaat om te zetten!

Kijk hier naar AbiAbdallahAwad die Markdown gebruikt om API’s in RAML te documenteren.

8. GhostDoc

Met GhostDoc, een Visual Studio extensie, kunt u eenvoudig uw XML-document commentaar genereren. De tool genereert commentaar op basis van meerdere factoren, waaronder naam, parameters, contextuele informatie, type, etc.

9. Natural Docs

Natural Docs is nog een andere open-source documentgenerator die met veel programmeertalen werkt. Het helpt u bij het automatiseren van het genereren van codedocumentatie en converteert deze naar HTML-indeling. Momenteel ondersteunt Natural Docs 19 talen, waaronder Python, C++, PL/SQL, Actionscript, etc.

10. phpDocumentor

Als je een PHP-ontwikkelaar bent en je wilt codedocumentatie genereren vanuit de broncode, kijk dan niet verder dan phpDocumentor. phpDocumentor is een unieke manier om met je codedocumentatie om te gaan en fungeert als een verwijzing naar de juiste documentatie. De belangrijkste kenmerken van phpDocumentor zijn PHP framework ondersteuning, pluggable architectuur, enz. Binnenwerk wordt beheerd door een krachtig en flexibel template systeem. De tool kan u ook helpen om rapporten en grafieken te genereren en de algehele kwaliteit van de code te verbeteren.

Bonus: Doc-O-Matic is een betaalde software voor het genereren van codedocumentatie. Lees er hier meer over.

Conclusie

Vandaag hebben we 10 tools voor perfecte codedocumentatie doorgenomen. Opgemerkt moet worden dat de hierboven genoemde tools dienen als aanvulling op je documentatieproces. Goede documentatie is nog steeds nodig, en mag niet worden genegeerd.