Informationen på denna sida är preliminär. Lita inte på det som står här.

Funktionshuvudskommentarer

En funktionshuvudskommentar underlättar läsning och förståelse av den skrivna koden samt gör det lättare att lokalisera vissa funktioner. Funktionshuvudskommentaren kan t.ex bestå av följande fält:

• Namn: Funktionshuvudet.
• Syfte: Talar om vad funktionen gör.
• Argument: Namn, typ och beskrivning av den information som skickas i varje eventuellt argument.
• Returnerar: Vad och av vilken typ funktionen returnerar.
• Precondition: Eventuella villkor som måste vara uppfyllda för att funktionen skall göra rätt. T.ex. kan filen /etc/passwd:s existens vara ett precondition, d.v.s. funktionen kräver att den filen finns för att göra rätt.
• Postcondition: Det som gäller efter att funktionen är färdig, om alla postconditions var uppfyllda. Kan t.ex. vara att filen /tmp/sort-passwd existerar.
• Kommentar: Övrig information, t.ex. algoritm.

Exempel:

/*------------------------------------------------------------------------
Namn: int sortPasswd(int (*compar) (const void *, const void *));
Syfte: Sorterar filen /etc/passwd med hjälp av funktionen compar,
och skriver den sorterade filen till /tmp/sort-passwd
Argument: int (*compar) (const void *, const void *) - en
pekare till en funktion som avgör i vilken ordning två
element skall sorteras
Returnerar: int - 0 om allt gick bra, annars 1
Precondition: Filen /etc/passwd måste finnas och vara läsbar
Postcondition: Filen /tmp/sort-passwd finns
Kommentar : Om compar är en NULL-pekare så kraschar funktionen.
Funktionen compar skall ta två argument och returnera 0 om
de är lika, -1 om det första argumentet skall vara före det
andra, och 1 om det andra argumentet skall vara före det
första.
------------------------------------------------------------------------*/

Usch så krångligt!

Nejdå. Du behöver självklart bara ha med de rubriker som behövs. Ett absolut minimum blir således Namn och Syfte, om funktionen inte har något argument eller returvärde, inte förutsätter något, inte har några sidoeffekter och inga kommentarer behövs.

Var skall (bör) man ha det någonstans?

I sin källkod före varje ny funktion.

Ja men det här står ju i (eller skall stå i) systembeskrivningen, måste man skriva om alltihop igen då?

Nej, om du skriver dessa huvuden redan vid kodningen så behöver du ju bara "klippa och klistra" in i rapporten. Se dock till att ta bort kommentar-tecknen och alla "---" ovanför och under, då du klipper in. Det blir mycket snyggare så.

Bör jag göra ungefär samma sak för structs?

Ja, det är en bra idé. En kommentar ovanför strukturen som säger vad den används till etc underlättar i framtiden.