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?
  • Wat levert de methode op? (javadoc @return)
  • Wat betekenen de parameters van de methode? (javadoc @param)

Standaard

Een goede standaard voor het documenteren wordt geautomatiseerd met Javadoc, een plugin die op steeds dezelfde manier deze documentatie kan maken voor Javascript, Typescript en Java, waar je dan alleen nog specifieke details hoeft toe te voegen.

Static site generators als Javadoc geven 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.

Functienaam

Je kan ervoor kiezen om de naam niet op te nemen, dat zie je direct in de eerste regel (bv public function(....) : void {).

Je kan er ook voor kiezen om bij de parameters niet het datatype op te nemen als je met een taal werkt waar dit expliciet wordt vermeld. Bij b.v. Python vermeld je het dan wel, omdat het in Python uit de code niet af te leiden is welke datatypes worden verwacht.

Los daarvan kan je ook nog benoemen wie de functie voor het eerst heeft geschreven, wanneer, een versienummer en nog meer. Zie Javadoc

Voorbeeld

Laten we zeggen dat we een klasse Playground hebben met wat losse functies om mee te spelen en van te leren hoe je code documenteert.

class Playground

class Playground

Nu gaan we 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);
system.out.println("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: int, b: int) : int
   return a* b;

def multiply(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

 @return : integer, the product of the 2 provided integers
*/

public multiply(a: int, b: int) : int
   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.

full_name : str = create_full_name("Philip","Lafeber");
system.out.println("Hello" + full_name + ".");

full_name = create_full_name("Guido","van Rossum");
print("Hello" + full_name + ".");

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.
 first_name: Str
 last_name: Str
 ...
 Return: str
*/
public create_full_name(first_name: str, last_name: str) : str
return first_name + " " + last_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
  """

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.

/*
 write_hello
 Writes hello on the screen
 @return: void  
*/
public write_hello(): void
system.out.println('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