Commentaar in code

De ene ontwikkelaar huivert er van, de ander kan er geen genoeg van krijgen: commentaarregels in code. Verhitte argumenten worden veelal over en weer gegooid binnen ontwikkelteams om deze ogenschijnlijk onschuldige stukjes tekst. Wat zijn nu eigenlijk de argumenten aan weerskanten? En wat vind ik er nu zelf van? Aan de hand van verschillende voorbeelden in C# neem ik je mee.

In onderstaande voorbeelden zie je een methode waar een leeftijd van iets of iemand wordt bepaald aan de hand van een datum.

public static int CalculateAge(DateTime? dateOfBirth)
{
    if (dateOfBirth == null)
        throw new ArgumentNullException(nameof(dateOfBirth));

    int returnValue = 0;

    if (dateOfBirth > DateTime.MinValue && dateOfBirth < DateTime.MaxValue)
    {
        DateTime today = DateTime.Today;

        int years = today.Year - dateOfBirth.Value.Year;

        DateTime last = dateOfBirth.Value.AddYears(years);

        if (last > today)
        {
            last = last.AddYears(-1);
            years--;
        }

        DateTime next = last.AddYears(1);

        double yearDays = (next - last).Days;
        double days = (today - last).Days;
        double exactAge = (double)years + (days / yearDays);

        returnValue = (int)Math.Floor(exactAge);
    }

    return returnValue;
}

/// <summary>
/// Calculates the age.
/// </summary>
/// <param name="dateOfBirth">The date of birth.</param>
/// <returns>An integer value</returns>
/// <exception cref="System.ArgumentNullException">dateOfBirth</exception>
public static int CalculateAge(DateTime? dateOfBirth)
{
    if (dateOfBirth == null)
        throw new ArgumentNullException(nameof(dateOfBirth));

    int returnValue = 0;

    if (dateOfBirth > DateTime.MinValue && dateOfBirth < DateTime.MaxValue)
    {
        // Get current date
        DateTime today = DateTime.Today;

        // Get the last birthday
        int years = today.Year - dateOfBirth.Value.Year;

        DateTime last = dateOfBirth.Value.AddYears(years);
        if (last > today)
        {
            last = last.AddYears(-1);
            years--;
        }

        // Get the next birthday
        DateTime next = last.AddYears(1);

        // Calculate the number of days between them
        double yearDays = (next - last).Days;

        // Calculate the number of days since last birthday
        double days = (today - last).Days;

        // Calculate exact age
        double exactAge = (double)years + (days / yearDays);

        returnValue = (int)Math.Floor(exactAge);
    }

    return returnValue;
}

Verschillende typen commentaar

In het bovenstaande voorbeeld wordt er in een van de methoden gebruik gemaakt van verschillende soorten commentaar. Elk van deze typen dient zo zijn eigen doel.

XML commentaar wordt veelal gebruikt om automatisch documentatie te genereren. Dit kan handig zijn om duiding te geven over wat de mogelijkheden zijn aan de gebruiker van de code. Denk hierbij aan de omschrijvingen die er gegeven worden op controller methoden in een Swagger pagina, of omschrijvingen zoals er in geautomatiseerde wiki’s te zien zijn.

Inline commentaar wordt met name gebruikt om duiding te geven aan complexe business rules en algoritmen, zoals bijvoorbeeld een formule die gebruikt wordt voor het bepalen van de omtrek van een ellips.

Functionele waarde

Functioneel gezien is er geen enkele toegevoegde waarde voor commentaar regels in code. Dat is simpelweg hoe de vlag er anno 2022 bij hangt. Echter ben ik van mening dat het schrijven niet simpelweg een functionele waarde moet hebben.

Niet-functionele waarde

Je hebt als ontwikkelaar de verantwoordelijkheid om je code eenvoudig en onderhoudsvriendelijk te maken. Tegenwoordig wordt daarom veelal het clean code principe toegepast, waar het idee is dat de code zo duidelijk moet zijn dat er geen commentaar benodigd is. Wat mij is opgevallen is dat dit niet altijd in de praktijk toegepast kan worden.

Bedrijven huren ontwikkelaars in omdat ze willen dat er een stuk software gemaakt wordt. Deze ontwikkelaars moeten er op hun beurt wel voor zorgen dat alle andere ontwikkelaars met deze code overweg kunnen wanneer dit nodig is. Door simpelweg principes toe te passen ben je er niet altijd. Deze principes zijn namelijk niet bij iedereen bekend, en er is geen garantie dat deze principes altijd relevant zullen blijven.

Daarnaast vind ik persoonlijk het esthetisch aspect van een bestand ook erg belangrijk. Mooi geformatteerd XML commentaar boven de verschillende methodes voelt voor mij als een soort kers op de taart. Het bijkomende voordeel is dat je inderdaad de mogelijkheid hebt om gebruik te maken van dit commentaar op andere plekken, zoals eerder omschreven.

Een belangrijke voorwaarde is dat het commentaar wat je schrijft ook inhoudelijk moet kloppen met wat er gebeurd. Het kan niet zo zijn dat het commentaar nooit wordt bijgewerkt wanneer de methode zelf wel bijgewerkt wordt.

Goed commentaar boven een methode heeft naar mijn mening ook een disciplinaire waarde voor jonge ontwikkelaars, en dwingt ze nog eens extra na te denken over de functie die ze zojuist hebben afgeleverd: kunnen ze deze uitleggen zonder de code te zien, en snappen ze wat er gebeurd?

Conclusie

De waarde van commentaar is dan in mijn optiek ook supplementair: het biedt de mogelijkheid voor extra functionaliteit, metadata en is, wanneer correct toegepast en bijgehouden, een toonbeeld van vakmanschap.