Commentaar in de code

Wanneer je aan het programmeren bent, zal je al vlug wennen aan het feit dat bijna elk karakter of woord dat je ingeeft een speciale betekenis heeft. Zo zal je bijvoorbeeld veel keywords zien in C# zoals class, namespace, public en vele anderen. Je zal ook zien dat de compiler er voor zorgt dat je deze keywords op een correcte manier gebruikt, evenals je eigen variabelen, methoden en functies. C# is een strikte programmeertaal en de compiler zorgt ervoor dat alles wordt ingegeven op de correcte manier. Toch bestaat er een manier om ervoor te zorgen dat je eender wat kan schrijven, met dank aan het concept commentaar.

Het is mogelijk dat je al voorbeelden hebt gezien van dit commentaar, is het nu in C# of eender welke andere programmeertaal. Het concept van commentaar is universeel. De manier waarop commentaar geschreven wordt verschilt echter sterk van programmeertaal tot programmeertaal. Laat ons even kijken hoe je commentaar kan toevoegen aan je code in C#.

Single-line commentaar

De meeste eenvoudige manier van commentaar in C# is het single-line commentaar. Zoals de naam reeds aangeeft, wijzigt dit één regel in je code in commentaar. Dit ziet er als volgt uit:

// My comments about the class name could go here...
class Program
{
    ......

Begin je regel met 2 slashes (//) en je tekst verandert van een regel die de compiler zou controleren (en waarschijnlijk over zou klagen) naar een regel die de compiler volledig negeert. Ook al werkt deze manier slechts voor één regel, niets houdt je tegen om dit ook te doen in de volgende regel. Op deze manier gebruik je single-line commentaar om toch meerdere regels commentaar in te geven:

// My comments about the class name could go here...
// Add as many lines as you would like
// ...Seriously!
class Program
{
    ...... 

Multi-line commentaar

Als je effectief meerdere regels commentaar wil schrijven is het misschien wel beter om de variant te gebruiken voor multi-line commentaar die C# ons aanbiedt. In plaats van elke regel individueel aan te duiden als commentaar kan je de startsequentie (/*) en stopsequentie (*/) gebruiken. Alles dat hier tussen staat wordt aanzien als commentaar:

/*  
My comments about the class name could go here...  
Add as many lines of comments as you want  
    ...and use indentation, if you want to!  
*/  
class Program  
{
    ......

Gebruik de startsequentie slash-asterisk (/*), schrijf wat je ook maar wil, verspreid over meerdere regels als je dat wil. Sluit dan af met de stopsequentie asterisk-slash (*/).

Vaak wordt er onder programmeurs gediscussieerd over welke variant het best gebruikt wordt. Zelf gebruik ik ze allebei, afhankelijk van de situatie. Zolang je niet met meerdere personen aan eenzelfde project werkt is die beslissing volledig zelf te nemen.

Commentaar ter documentatie

Commentaar ter documentatie (soms ook XML commentaar ter documentatie genoemd) ziet er bijna hetzelfde uit als normaal commentaar, maar dan met embedded XML. Ook hier kan je zoweel single-line als multi-line commentaar gebruiken. Je schrijft ze op dezelfde manier, maar met een extra karakter. Single-line XML commentaar ter documentatie gebruikt 3 slashes (///) in plaats van 2. De multi-line variant gebruikt een extra asterisk in de startsequentie. Laat ons even kijken hoe dit er uitziet:

class User
{
    /// <summary>
    /// The Name of the User.
    /// </summary>
    public string Name { get; set; }

    /**
    * <summary>The Age of the User.</summary>
    */
    public string Age { get; set; }
}

Hier zie je beide varianten, single-line en multi-line. Het resultaat is hetzelfde, maar de eerste variant wordt meestal gebruikt voor commentaar ter documentatie.

Documentatie van de gebruikte types en hun leden met commentaar ter documentatie is een belangrijk onderwerp en daarom zullen we er dieper op ingaan in een volgend artikel. Maar nu weet je toch al hoe ze er uit zien.

Commentaar bij je code & de Task list

Als je Visual Studio gebruikt, kan je hulp krijgen bij het opvolgen van je commentaar. In het Task list venster (dit kan je vinden in het menu View > Task List) zal je commentaar verschijnen als je volgende Task list commentaar syntax gebruikt:

//TODO: Change "world" to "universe"
Console.WriteLine("Hello, world!");
//HACK: Don't try this at home....
int answerToLife = 42;

Als de startsequentie voor single-line commentaar direct gevolgd wordt door TODO of HACK, zal het verschijnen in de Task list van Visual Studio, zoals je hier ziet:

Er zijn nog meer types, afhankelijk van welke versie van Visual Studio je gebruikt zullen volgend comment token ook verschijnen in de lijst:

• TODO
• HACK
• NOTE
• UNDONE

Indien gewenst kan je ook je eigen tokens aanmaken, volg gewoon de stappen beschreven in dit artikel.

Samenvatting

Commentaar is zeer handig om je code te documenteren of om hints voor jezelf (of eventuele collega's) bij je code te plaatsen die kort uitlegt hoe alles werkt. Als toegevoegde waarde zijn ze ook zeer nuttig om kleine aanpassingen in je code vlug te testen. Kopieer de oorspronkelijke regel code, pas deze aan en plaatst de oorspronkelijke regel in commentaar. Indien de aanpassing niet het gewenste resultaat geeft kan je de nieuwe regel opnieuw verwijderen en de oorspronkelijke regel terug uit commentaar halen.

Maak je ook geen zorgen over eindgebruikers als je commentaar gebruikt. Zoals reeds vermeld wordt alle commentaar volledig genegeerd door de compiler en dus ook niet inbegrepen in EXE of DLL bestand. Commentaar is er enkel voor jou om te helpen, dus gebruik het zoals je zelf wil.