Iedereen die wel eens een stuk code heeft moeten analyseren weet hoe belangrijk commentaar is. Commentaar tussen complexe programmeercode biedt inzicht in de wijze waarop de ontwikkelaar/auteur van het stuk code te werk is gegaan.

Bij het begrijpen en eventueel moeten aanpassen van stukken programmeercode is toegevoegde commentaar onmisbaar. Voor elke ontwikkelaar is het toevoegen van commentaar een goede gewoonte. Zelfs als de code alleen voor eigen gebruik is bedoeld, kan commentaar de ontwikkelaar na verloopt van tijd inzicht geven in de wijze waarop de ontwikkelaar zelf te werk was gegaan.

Op het moment van schrijven begrijp je vaak hoe jouw code werkt en waarom, maar als je opeens na 3 jaar aanpassingen iets nieuws moet doorvoeren dan kan het zijn dat je niet meer precies weet hoe het ook al weer in elkaar steekt.

Een andere reden om zoveel mogelijk commentaar toe te voegen is voor het geval er andere mensen aan je script moeten werken. Wat voor jouw destijds normaal leek is voor iemand anders misschien helemaal niet zo logisch. Het maakt voor de prestaties van je script niet uit hoeveel commentaar je gebruikt, het zal dan ook nooit kunnen leiden tot performance verlies of andere nadelige gevolgen hebben.

Kortom, het toevoegen van commentaar doe je om duidelijkheid te scheppen en je code makkelijker te beheren/onderhouden.

Een paar redenen om commentaar toe te voegen:
1) Na een lange periode weet je niet meer waarom je bepaalde keuzes hebt gemaakt en wat bepaalde functies precies doen.
2) Voor de mate van beheer/wijzigingen door anderen is commentaar onmisbaar.
3) Scheelt frustraties, doorlooptijd en geld!
4) Elke goede ontwikkelaar voegt commentaar toe aan zijn/haar programmeercode.
5) Just do it!

We onderscheiden twee soorten commentaar, namelijk het toevoegen van 1 commentaarregel (lijn commentaar) of het uitcommentariëren van een stuk code van meerdere regels (block commentaar).

Hieronder zie je een overzicht van de verschillende opties t.a.v. commentaar toevoegen per programmeertaal:

Lijn commentaar

ALGOL 60 ;   (semicolon)
Assembly Languages ;   (semicolon)
Ada, mySQL   (two dashes)
C++/Java //  (two slashes)
FORTRAN 90 !   (exclamation mark)
Perl, TCL, UNIX Shell, mySQL #   (hash sign
Visual Basic .NET ‘   (apostrophe)

 

Block commentaar

ALGOL comment “ends with” ;
Pascal (* . . . *)  or { . . . }
Many languages /* . . . */
Forth ( . . . )
HTML <!– . . . –>
Haskell {-   -}
Unix <<COMMENT1…COMMENT1