Commentaar

Vraag een programmeur wat het belangrijkste is aan een omvangrijk project, en menigeen zal antwoorden dat dat het commentaar is. Dat licht toe wat je code doet, hoe het werkt en waarom je het op die manier doet. Uit PEAR pakketten worden commentaarblokken zelfs uit de code geabstraheerd en vrijwel automatisch tot aparte documentatie verheven.

Het is echter moeilijk om het commentaar correct te doseren; niet alleen kan je te weinig commentaar hebben, ook teveel commentaar komt de leesbaarheid (en bestandsgrootte) niet ten goede:

In bovenstaand voorbeeld is eigenlijk in het geheel geen commentaar nodig. Voor iedereen zal duidelijk zijn wat bedoelt wordt met een if-else statement. Voor ingewikkeldere of grotere stukken code kan het wel verhelderend zijn om aan te duiden om welke variabele het gaat of wat het doet.
Wanneer moet je commentaar plaatsen? Dat is een beetje natte vingerwerk, maar je kunt het volgende aanhouden: wanneer je naar een stuk code kijkt en denkt “Potjandorie, ik ga niet proberen om te beschrijven wat dat doet!”, heb je commentaar nodig. Voeg dat commentaar in terwijl je typt of vlak erna, voordat je vergeet hoe je code in elkaar steekt.

De globale en soms meer gedetailleerde beschrijving van een bestand of klasse plaats je overigens bovenaan het bestand, in zogenaamde docblocks. Het gebruik van die docblocks ga ik niet verder uitleggen, gezien weinigen hier ook daadwerkelijk hun code aan PEAR ter beschikking zullen stellen. Mocht je dat wel doen, dan verwijs ik je naar de Engelse tekst van de codeerstandaard.

Commentaar in de stijl van C (/* */) en standaard C++ commentaar (//) is overigens allebei prima. Het gebruik van de Perl/shell commentaarstijl (#) wordt daarentegen afgeraden.

« Lees de omschrijving en reacties