Waarom is documentatie zo belangrijk?

Laten we eerlijk zijn, niemand wil documentatie schrijven. Het schrijven van code is leuker en documentatie heeft geen effect op de werking van de code. Dus waarom zou iemand ooit code documenteren? 

Andere redenen dat niemand documentatie wil schrijven:

• Code verandert snel en vaak waardoor de documentatie out-of-date kan zijn.
  Op het moment van schrijven van de code verandert er van alles aan de code en kan een bepaalde functie ineens iets compleet anders doen waardoor een deel van je documentatie niet meer klopt. Dit ook nog moeten onderhouden naast de codebase kan heel vervelend zijn.
  
• Pogingen tot documentatie leiden eigenlijk tot een refactor sessie.
  Op het moment dat je de code uit moet leggen kom je erachter dat de code eigenlijk helemaal niet duidelijk is en dat het beter is om bepaalde stukken te herschrijven.
• Er moet geld binnenkomen
  Natuurlijk moet er in het bedrijfsleven ook geld verdiend worden en aangezien de meeste klanten betalen voor een product of dienst waarvan ze de broncode nooit zien, is het een verspilling van tijd en geld om code te documenteren.
• Je code is slecht en je wilt het niet toegeven
  We schrijven allemaal wel eens een stuk slechte code, maar door het op te schrijven en te documenteren geven we eigenlijk toe dat we slechte code hebben geschreven en wie wil nou toegeven dat ze slechte code schrijven.

Eigenlijk is geen van de bovenstaande een goede reden om geen documentatie te schrijven.

• Code verandert snel en vaak waardoor de documentatie out-of-date kan zijn.
  Code kan veranderen maar waarom zou de documentatie dat niet kunnen?
• Pogingen tot documentatie leiden eigenlijk tot een refactor sessie.
  Het verbeteren van code en efficiëntere logica inbouwen is goed. Hierdoor voorkom je bugs. Ook geeft dit aan dat de code nog onstabiel is en er dus ook geen distributie van de code zou moeten plaats vinden.
  
• Er moet geld binnenkomen
  Geld moet uiteraard gewoon binnenkomen dus er moet productie worden gedraaid. Echter kost het oplossen van bugs ook tijd en dan is het wel zo fijn als je weet wat welke functie doet en waarom er bepaalde dingen gebeuren.
• Je code is slecht en je wilt het niet toegeven
  Slechte code is slecht en je zou je slecht moeten voelen als je slechte code schrijft! 

Dus waarom zou je juist wel documentatie schrijven? 

• Niet alle developers hebben evenveel kennis van het project. Niet alleen de personen die aan het project hebben gewerkt maar ook nieuwe developers zouden de code moeten kunnen begrijpen.
• Niet alle code is duidelijk te begrijpen en leesbaar te maken zonder commentaar en documentatie. Zeker als je met algoritmes gaat werken, ga je al snel de mist in.
• Details uitzoeken - zeker tijdens bugfixes of na een afwezigheid in een project - kost veel tijd op zich. Wanneer je geen documentatie hebt, duurt het al snel vele malen langer. 
• Als je elke methode van elke class hebt gedocumenteerd is het veel makkelijker om eventuele vragen te beantwoorden.
  
• Het is een kleine moeite om te documenteren tijdens het schrijven van je code. De meeste IDEs kunnen zelfs grote stukken documentatie automatisch genereren. Het enige wat je dan nog zelf hoeft te doen, is een korte omschrijving toe te voegen. 

De bovenstaande punten vatten we mooi samen in onderstaand voorbeeld:

Henk van de administratie belt met de opmerking dat er in de boekhouding 13 facturen missen in de export van de maand januari maar dat ze wel in het systeem staan. De stagiair gaat naar dit probleem kijken en kijkt in de logs. De logs bevatten geen fouten, dus het probleem moet ergens anders zitten. In een project waar geen documentatie is, wordt het erg lastig om snel te zien waar wat zit. Zeker voor de stagiair die nog niet helemaal thuis is in het project. Als je echter weet welke classes of methodes er worden gebruikt en waarom de code op een bepaalde manier is geschreven voor het ophalen van de data is het veel makkelijker om te achterhalen waar wellicht het probleem zit. 

/**
 * Get the invoices based on the month
 *
 * @param $month String
 * @return Invoice
 */
getInvoicesByMonth($month) {
    // get the invoices in chunks of 100 to avoid memory overflow
    return Invoice::month($month)->take(100)->get();
}

Het begint bij de code

Documentatie is extreem belangrijk en er zou zo vroeg mogelijk moeten worden gedocumenteerd. Wanneer wil je weten of je logica klopt? Vroeg in het ontwikkelproces of achteraf na een release als er eindelijk tijd is voor het schrijven van de documentatie? Uiteraard wanneer er nog aan de code wordt gewerkt zodat je de code gelijk kan verbeteren! 

Als je de code niet duidelijk kan documenteren houdt het waarschijnlijk in dat je de code niet (goed) begrijpt. Als je de code niet begrijpt, moet je je afvragen of je code überhaupt wel in het project thuis hoort. Als je de code kan documenteren maar het niet doet, is het vragen om problemen.  

Commentaar en documentatie zou moeten uitleggen waarom iets gebeurt, niet hoe iets gebeurt. Ook is het gebruik van duidelijke benaming al een groot deel van de documentatie. 

Zie onderstaand voorbeeld:

// Convert to cents 
$amt = $amt * 100;

Stel dat we over 100 regels nog een keer $amt nodig zouden moeten hebben, dan is het niet duidelijk wat er nu in zit. Is het het bedrag of het totaal aantal centen. Waarom willen we eigenlijk het totaal aantal centen hebben en is een bedrag niet goed? In onderstaand voorbeeld is het een en ander aangepast en is de code een stuk duidelijker:

// Convert to cents for the Payment Service Provider
$totalCents = $amount *100;

Wat we absoluut moeten voorkomen in de code is “comment-code redundancy”. Oftewel commentaar in de code die eigenlijk niks toevoegt. Zie onderstaand voorbeeld: 

$i++; // increments $i by 1; 

Ook zou elke methode en elke class een stuk documentatie moeten hebben. Waarvoor dient de class, wat is het doel van de methode, etc. 

Afsluiting

Documenteren is nu eenmaal een taak die developers niet graag op zich nemen. Toch is het een serieus deel van het werk als developer om (goede) documentatie te schrijven. Zeker als er andere mensen aan mee werken. Er zijn twee soorten developers, zij die hun code documenteren en luie developers. En ik vertrouw geen code van luie developers. 

Een ander goed artikel over dit onderwerp:
https://hackernoon.com/what-the-was-i-thinking-how-to-write-understandable-code-6162b363e735