Commentaar (programmeren)

In programmeertalen is commentaar een taalconstructie om informatie aan de broncode toe te voegen. Deze gedeelten van de broncode worden door de interpreter of compiler niet gebruikt bij het verwerken van de broncode. Ook andere computertalen, zoals HTML, kunnen commentaar bevatten. Commentaar heeft voornamelijk als doel de werking van de broncode toe te lichten, maar het kan ook gebruikt worden om automatisch documentatie te genereren.

Overzicht

De broncode van een computerprogramma kan onderverdeeld worden in uitvoerbare code (instructies die omgezet kunnen worden naar machinetaal) en commentaar (leesbare tekst met voor mensen leesbare opmerkingen en toelichtingen). Commentaar kan verdeeld worden in twee soorten: commentaar op een enkele regel (line comments, regelcommentaar) en commentaar dat mogelijk meerdere regels beslaat (block comments, blokcommentaar).

Welke gedeelten commentaar zijn, wordt doorgaans aangegeven met bepaalde tekens die het begin of eind van het commentaar aangeven. Commentaar dat op een regel staat, wordt aangegeven met een of meerdere tekens (zoals // in C++ en Java of -- in Haskell) en het loopt door tot de eerstvolgende regelovergang. Commentaar dat meerdere regels beslaat, wordt aangegeven met een of meerdere tekens voor en na het commentaar (zoals /* en */ in C, C++ en Java en {- en -} in Haskell). Sommige talen, zoals MATLAB en Haskell, staan toe dat meerdere blokken commentaar in elkaar zijn geplaatst terwijl andere talen, zoals Java, dit niet toestaan.[1]

Niet alle talen ondersteunen beide soorten commentaar. C++ ondersteunt beide vormen van commentaar terwijl bijvoorbeeld in Ada alleen regelcommentaar mogelijk is (met --).

Met name esoterische programmeertalen gebruiken een beperkt aantal tekens voor de uitvoerbare instructies, zoals Brainfuck en Whitespace, en alle andere tekens worden genegeerd. Het is dan mogelijk de broncode van commentaar te voorzien zolang daarin geen tekens gebruikt worden die wel een betekenis hebben bij het uitvoeren van de broncode. In andere esoterische programmeertalen, zoals Befunge, kan men de uitvoering van de broncode zodanig sturen dat bepaalde gedeelten van de broncode geheel niet gebruikt worden; op deze plekken kan men dan commentaar plaatsen.

Commentaar dient ook bijgewerkt te worden als de code aangepast wordt om later verwarring te voorkomen.[2] Bij het gebruik van automatisch refactoren is het van belang dat het commentaar ook bijgewerkt wordt.[2]

Commentaar wordt ook gebruikt om gegevens over het auteursrecht en (een verkorte versie van) de licentie van vrije software op te nemen aan het begin van elk broncodebestand.

Genereren van documentatie

Commentaar waaruit documentatie wordt gegenereerd dient vaak in een bepaalde opmaak geschreven te worden.[1] In Java kan men bijvoorbeeld met @param de parameters van een methode toelichten en na @return volgt een toelichting over de waarde die de methode oplevert. Met @deprecated kan men aangeven dat een methode verouderd is en niet langer gebruikt dient te worden. Doordat deze informatie in een vastgelegde opmaak is geschreven, kan een IDE de programmeur er ook op attenderen dat de methode verouderd is.

In Visual Basic en C# kan commentaar in XML worden geschreven; dit worden "XML comments" genoemd. Dit commentaar wordt gebruikt door IntelliSense in Visual Studio om meer informatie te tonen.

Gebruik en inhoud

Er zijn allerlei meningen over het gebruik en de inhoud van commentaar in softwareprojecten. In The Elements of Programming Style van Brian W. Kernighan en P. J. Plauger wordt gesteld: "Becommentarieer geen slechte code - herschrijf het.". In Code Complete stelt Steve McConnell: "Goed commentaar is geen herhaling of uitleg van de code. Het verduidelijkt de intentie. Commentaar dient op een hoger abstractieniveau dan de code uit te leggen wat je probeert te doen.".

De achterliggende visie is dat de code zo duidelijk dient te zijn dat een toelichting in commentaar niet nodig is.[2] Het uitleggen van de code in commentaar kan een teken zijn dat de code te complex is. Commentaar kan wel nodig zijn om uit te leggen waarom een bepaald stuk code niet voldoet aan standaarden of aan de gangbare manier om een probleem op te lossen.

Anderen beargumenteren dat code rijkelijk voorzien dient te zijn van commentaar.

Niveau

Qua inhoud dient commentaar overeen te komen met het doel waarvoor de code geschreven is. Het soort commentaar dat acceptabel is in code voor een inleidend boek over programmeren, is niet acceptabel in een softwareproject waar ervaren programmeurs samenwerken. Om te leren hoe een stuk code werkt, kan het nuttig zijn als bepaalde regels voorzien zijn van commentaar dat de semantiek van de programmeertaal toelicht, bijvoorbeeld: 

// maak een array steden met drie String-elementen
String[] steden = { "Amsterdam", "Melbourne", "New York" };

In specialistische software wordt commentaar ook gebruikt om theoretische aspecten uit te leggen in verhouding tot de wijze waarop deze geïmplementeerd zijn.

Taalgebruik

Soms wordt commentaar in broncode gebruikt om stress te verminderen of om kritiek te leveren op de gebruikte ontwikkelprogramma's, medewerkers, werk-omstandigheden, de kwaliteit van de code of andere bedrijven in dezelfde markt.[3]

Uitcommentariëren

Zie Uitcommentariëren voor het hoofdartikel over dit onderwerp.

Commentaar wordt ook voor een ander doel gebruikt: door uitvoerbare code in commentaar te plaatsen, worden deze regels in feite uit het programma gehaald en niet meer uitgevoerd. De programmeur kan zo bepaalde stukken code 'uitschakelen' tijdens het ontwikkelen van het programma om te kijken wat het effect hiervan is. Deze bezigheid wordt het uitcommentariëren van broncode genoemd. Dit wordt met name gedaan bij het debuggen van de code.

Standaardtermen

Commentaar wordt ook gebruikt om bepaalde plekken in de broncode aan te duiden waar nog iets mee moet gebeuren, zoals een bug die gerepareerd moet worden of een stuk code dat nog geschreven moet worden. Hiervoor worden vaak standaardtermen of tags gebruikt zodat men makkelijk de broncode kan doorzoeken om deze plekken te vinden.[4]

Deze termen zijn:

  • TODO (voor een verandering die nog moet gebeuren),
  • FIXME (een bug of onjuistheid die aangepast moet worden),
  • NOTE en XXX (om problematische gedeelten van de code te verduidelijken of aan te geven).

In sommige IDE's wordt syntaxiskleuring gebruikt om deze termen duidelijk te onderscheiden van de rest van het commentaar.[4] In Eclipse kan men via de Tasks-view een overzicht verkrijgen van deze plekken in de broncode.[5] Men kan ook grep gebruiken om deze regels terug te vinden.[4]

In een softwareproject kunnen er ook richtlijnen zijn voor welke standaardtermen gebruikt worden.[4] Er kan ook aanvullende informatie worden verstrekt, zoals de datum, de naam van degene die de term geplaatst heeft en/of een toelichting van wat er precies aan de hand is.[4] Hierdoor kan men zien wie de meeste tags heeft geplaatst en hoelang bepaalde tags al aanwezig zijn in de broncode.[4]