Elke developer weet dat je code duidelijk gedocumenteerd moet zijn. Toch gebeurt dit vaak nog te weinig of gewoon niet op de juiste manier waardoor je documentatie eigenlijk zijn doel mist. In deze blogpost wil ik graag de meest gebruikte smoesjes om het niet te doen oplijsten en nog eens de voordelen benadrukken. Als laatste geef ik nog enkele tips mee over hoe je betere documentatie schrijft.

Smoesjes om het niet te doen

Elke goede developer begrijpt deze code toch?

Dit is volgens mij het meest gebruikte excuus. Zelfs al is je code duidelijk geschreven en is het makkelijk leesbaar, dan betekent het nog steeds niet dat je code ook begrijpbaar is. Duidelijke documentatie zorgt ervoor dat je collega's je minder vaak storen om te vragen wat dat ene stukje code ook al weer deed. Ook kan je op dit moment je code wel goed begrijpen, maar weet je dit over een jaar nog steeds?

Ik geef alles een duidelijke naam. Meer is toch niet nodig?

Het duidelijk benoemen van je variabelen en functies is zeker een meerwaarde voor je code. Maar een naamgeving zal nooit meer zijn dan een omschrijving van je functie in enkele (vaak afgekorte) woorden.

Hier heb ik geen tijd voor!

Ook al heb je weinig tijd om een project tot een goed einde te brengen, tijd maken voor het schrijven van documentatie kan je in de toekomst, wanneer de klant nog snel een aanpassing wilt, veel tijd besparen doordat je niet bij elke regel moet denken: "Waarom heb ik dit zo weer gedaan?" of "Wat deed dit weer?".

Een goed voorbeeld

Onderstaand kan je een voorbeeld terugvinden van duidelijke documentatie.  De documentatie van deze functie laat je weten dat alle voorgaande afzenders uit de lijst worden verwijderd, iets wat niet duidelijk is als je alleen de functienaam had.

/**
 * Sets the recepient of this message, calling this method also clears any
 * previously set recepients in the TO stack.
 * @param string $email
 * @param string $name
 * @return Mailer
 */
public function setTo($email, $name = null)
{
    $this->clearTo();
    $this->addTo($email, $name);
    return $this;
}

Voordelen

Code onafhankelijk van ontwikkelaar

Wanneer je met meerdere ontwikkelaars werkt aan een project is het zeker een plicht je documentatie up-to-date te houden. Maar zelfs wanneer je alleen aan een project werkt moet je er rekening mee houden dat je project wel eens naar een andere ontwikkelaar kan worden doorgeschoven of dat je van job verandert en je er dus niet meer aan zal werken.

Na geruime tijd begrijp je je eigen code niet meer

Wanneer je code gedurende lange tijd onveranderd blijft krijg je vaak schrik om je code nog aan te passen. Je hebt schrik dat je bij elke aanpassing wel ergens anders iets kapot maakt. Goede documentatie geeft je het zelfvertrouwen om je code aan te passen zonder iets kapot te maken.

Auto-complete bij gebruik van IDE

Er wordt op de dag van vandaag veel gebruik gemaakt van IDE-tools die je code hinting geven. Hier zal goed geschreven documentatie jezelf, en de rest van het team, veel tijd besparen. Zo zie je direct een omschrijving van de aan te roepen functie zonder dat je telkens opnieuw dat ene bestand moet zoeken waar die functie staat. Om daarna de code door te nemen om te achterhalen wat het resultaat zal zijn.

Tips

Schrijf je commentaar altijd in dezelfde taal

Het gebruik van eenzelfde taal in je documentatie zorgt voor consistentie. Je gaat variabelen ook niet half in het Nederlands, half in het Engels benoemen? Wanneer je in een team werkt maak je dan ook best afspraken over de taal van je documentatie, al is het aan te raden om je volledig op Engelse documentatie te richten.

Documenatie gaat over wat je code doet

Documentatie heeft niet als doel om je code te verantwoorden of een excuus te geven waarom de code er zo slecht uitziet, maar meer om uit te leggen wat de code juist doet en waar het rekening mee houdt.

Hou het leuk!

Als laatste is het altijd wel eens leuk om een leuke opmerking in je code stoppen waar je zelf, en je collega's, eens mee kunnen lachen. Iedereen kent de regel "stop(); // Hammertime" wel. Een uitgebreide lijst met hilarische documentatie kan je op Stackoverflow terugvinden.