Skip to content

Code commentaar

Wanneer je herbruikbare code maakt in een functie, dan betekent dit dat de functie elders toepasbaar is zonder wijzigingen en zonder fouten.

Een andere ontwikkelaar moet de functie dan ook toe kunnen passen. Daarvoor hoeft deze de code niet te kennen. Het is alleen nodig om te weten hoe de functie werkt. Daarvoor is documentatie nodig. Dat schrijven we direct boven de functie in commentaar (als we met Javascript, Typescript of Java werken) of direct onder de declaratie van de functie (als we met Python werken). In Javascript en Typescript staat het dan tussen /* en */. In Python staat het achter een # op elke regel.

Engelse taal

Let er op dat je code en de documentatie in het Engels schrijft. Zo is het resultaat ook uitwisselbaar met mensen buiten Nederland.

Elke methode, klasse of attribuut moet voorafgegaan worden door een toelichting:

  • Wat is het doel van het stuk code?
  • Wat zijn de parameters die gebruikt worden in het stuk code? (@param)
  • Wat levert de methode op? (@return)

Doc comments

Doc comments zijn bedoeld om de functionaliteit van code-elementen (zoals klassen, methoden, variabelen) te beschrijven op een manier die gemakkelijk te begrijpen is voor andere ontwikkelaars, zelfs als ze de broncode niet tot in detail kennen.

Je kunt Doc comments ook gebruiken om om automatisch documentatie te laten genereren bijvoorbeeld in de vorm van een documentatie website.

Een documentatiegenerator is een computerprogramma waarmee automatisch documentatie gegenereerd kan worden uit commentaar in de broncode.

Automatisch documentatie laten genereren betekent wel dat je volgens een bepaalde documentatie standaard dient te werken.

Afhankelijk van de taal die je gebruikt zijn er verschillende documentatie standaarden:

Er zijn verschillende tools om je ‘doc comments’ te exporteren naar een externe vorm: bijvoorbeeld een HTML website of Markdown bestanden.

De ‘doc’ standaard geeft de mogelijkheid om heel veel onderwerpen op te nemen in de documentatie, maar de meest essentiële zijn:

  1. De naam van de functie zelf
  2. De toepassing van de functie, waar deze voor bedoeld is. Je beschrijft dus niet hoe de functie werkt, dat kan je halen uit de code.
  3. Elke parameter die de functie aanneemt om het werk uit te voeren, inclusief het datatype.
  4. De uitvoer (return) terug aan de aanroepende code, als datatype.

Voorbeelden

We gaan een functie definiëren die van 2 getallen het product uitrekent en teruggeeft aan de code die deze functie aanroept. We willen die functie zo aan kunnen roepen;

product1 = multiply(2,4);
console.log("Het product van 2 en 4 is " + product1);

product1 = multiply(2,4);
print("Het product van 2 en 4 is " + product1);

Deze functie definiëren we dan als volgt:

public multiply(a: number, b: number) : number {
  return a * b;
}

def multiply(a,b)
  return a * b

Afhankelijk van de programmeertaal documenteren we deze functie in het volgende stramien.

/*
  Naam
  Beschrijving
  Parameter 1
  Parameter 2
  ...
  Return
*/

"""
Beschrijving

Args: 
  Parameter 1 (datatype): beschrijving
  Parameter 2 (datatype): beschrijving
  ...
Returns:
  datatype: beschrijving
"""

Dit wordt dan:

/*
  Multiply
  Used to calculate the product of 2 integers.
  @param a the first of the 2 integers
  @param b the second of the 2 integers
  @returns integer, the product of the 2 provided integers
*/
public multiply(a: number, b: number) : number {
  return a * b;
}

def multiply(a,b):
  """
    Multiply
    Used to calculate the product of 2 integers.

    Args:
      a (int) : the first of the 2 integers
      b (int) : the second of the 2 integers

    Returns:
      int: the product of the 2 provided integers
  """
  return a*b

In het volgende voorbeeld doen we hetzelfde voor een andere functie met andere datatypes als argument en return value. We willen code schrijven om iemands volledige naam op het scherm te printen. Dit kan je voor elkaar krijgen door een functie te specificeren die deze twee strings verwerkt en als één string teruggeeft.

/*
  Create full name
  Combines first name and last name into one string.
  @param first_name: string
  @param last_name: string
  @returns string
*/
public createFullName(first_name: string, last_name: string) : string {
  return first_name + " " + last_name;
}

full_name : str = createFullName("Mick","Jagger");
console.log("Hello" + full_name + ".");

create_full_name(first_name,last_name):
  """
    Create Full name
    Combines first name and last name into one string.

  Args:
    first_name (str): The person's first name
    last_name (str): The person's last name

  Returns:
    str: the combined name
  """
  return first_name + " " + last_name

full_name = create_full_name("John","Lennon");
print("Hello" + full_name + ".");

In sommige gevallen is er geen return value. De functie wordt dan uitgevoerd en houdt op zodra de code is uitgevoerd. Dan vermeld je wel de return value, maar dat is in dit geval niks, oftewel ‘void’. In Typescript moet je dit aangeven in de code, in Python hoeft dit niet.

/*
  writeHello
  Writes hello on the screen
  @returns void  
*/
public writeHello(): void {
  console.log('Hello!');  
}

def write_hello():
  """
    write_hello
    Writes hello on the screen      
  """
  print("Hello!")

Inhoud

Commentaar moet het waarom toelichten en niet herhalen wat er al staat.

Fout voorbeeld

index++; // verhoog index met 1

Goed voorbeeld

index++; // verwijs naar volgende student in de rij

Bronnen