nästa upp förra
Nästa: Deklarationskommentar Upp: cdok Konventioner för kommentarer Förra: Funktionskommentar:

Procedurkommentar

Varje procedur föregås av en procedurkommentar som förklarar vad proceduren gör och vad den påverkar (variabler, filer ...).

Börja alltid kommentaren med: procedurnamn huvudverb etc. etc. dvs: getline reads one line ... Med fyra ord har du talat om vad getline gör i stora drag. Och det är "reads" som är det viktigaste verbet här.

Rena procedurer har inget returvärde, utan påverkar sin omgivning enbart via sina argument. Detta innebär att det viktigaste för en procedur är vad den påverkar (vilka variabler) och vilken denna påverkan är. Procedurkommentaren skall altså helt specificera hur det omgivande tillståndet förändras när proceduren anropas.

Det skall räcka med att läsa procedurkommentaren (och deklarationskommentarerna för parametrarna) för att kunna förstå och använda proceduren.

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

Användning av parameternamn i procedurkommentarer bör ofta undvikas av samma skäl som för funktionskommentarer. Motsvarande gäller användning av variabelnamn i procedurkommentarer.

Procedurkommentar

/** getline
 *
 * getline reads one line from stdin and stores it in 
 * the given buffer. The newline is stored.
 *
 * The given buffer must be big enough to store the trailing '\0' 
 * (i.e. it must be at least one bigger than nmax).
 *
 */

void
getline (
    char   buf[],  /* IN: where to store line        */
    int    nmax,   /* IN: max #chars to read         */
    int   *nread)  /* OUT: #chars read, 0 means EOF  */



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