nästa upp förra
Nästa: Procedurkommentar Upp: cdok Konventioner för kommentarer Förra: Datatypskommentar

Funktionskommentar:

Varje funktion föregås av en funktionskommentar som förklarar vad funktionen återlämnar för värde, och oftast hur värdet är definierat (vilket inte behöver vara samma sak som hur det beräknas).

Börja alltid kommentaren med: funktionsnamn returns värde som återlämnas

Rena funktioner innehåller inte sidoeffekter, ändrar inte på globala variabler, tittar inte på globala variabler samt anropar inte procedurer. Detta medför att det viktigaste för en funktion är vad den återlämnar. Det skall räcka med att läsa funktionskommentaren (och parameterkommentarerna för parametrarna) för att kunna använda eller implementera funktionen.

Att funktionskommentaren och parameterkommentarna helt specificerar semantiken hos funktionen (dvs att vad den gör är väldefinierat), innebär att man ska kunna implementera funktionen mha denna specifikation, trots att inget sägs om hur den gör det.

Kommentartexten flyter ofta bättre, om man i den informella delen refererar till parametrar med konstruktioner som the given length istället för med parameternamnet (t.ex. len). Dessutom slipper man då ändra i kommentaren om man byter namn på parametrarna. Kommentaren ska inte innehålla referenser till lokala variabler i funktionen.

Funktionskommentar

/** zexp
 *
 * zexp returns the exponential of a complex number. 
 * 
 * Def:
 *     zexp (a + b * i) = exp (a) * exp (b * i) 
 *                      = exp (a) * (cos (b) - i * sin (b)) 
 *                      = exp (a) * cos (b) + i * exp (a) * sin (b)
 *
 */
Complex *
zexp (
    Complex *z);

Två funktionskommentar för en list-ADT

/** list_empty
 *
 * list_empty returns true if the list is empty
 * and false otherwise.
 *
 * Def:
 *     list_empty (list)  ==  (list_size (list) == 0)
 *
 */
bool
list_empty (
    List   *list);

/** list_after
 *
 * list_after returns the special position 
 * that is after the position of the last element.
 *
 * Def:
 *     list_after (list) == list_pos (list, list_size (list))
 * 
 */
Pos 
list_after (
    List   *list);



Jonas Mölsä
Sat Sep 13 13:46:34 MET DST 1997