Recommandations :
Dans le domaine général de la programmation, (pas seulement le langage C),
il est admis qu'il faille commenter selon les niveaux suivants :
- -
- unité de compilation : pour indiquer le nom de l'auteur, les droits de
copyright, la date de création, les dates et auteurs des différentes
modifications, ainsi que la raison d'être de l'unité ;
- -
- procédure : pour indiquer les paramètres et la raison d'être de la
procédure ;
- -
- groupe d'intructions : pour exprimer ce que réalise une fraction
significative d'une procédure ;
- -
- déclaration ou instruction : le plus bas niveau de commentaire.
Pour le niveau unité de compilation, voici un exemple tiré du source de perl :
/*
* Copyright (c) 1991, Larry Wall
*
* You may distribute under the terms of either the GNU General Public
* License or the Artistic License, as specified in the README file.
*
* $Log: perl.c,v $
* Revision 4.0.1.8 1993/02/05 19:39:30 lwall
* Revision 4.0.1.7 92/06/08 14:50:39 lwall
* Revision 4.0.1.3 91/06/07 11:40:18 lwall
* Revision 4.0.1.2 91/06/07 11:26:16 lwall
* Revision 4.0.1.1 91/04/11 17:49:05 lwall
* Revision 4.0 91/03/20 01:37:44 lwall
* 4.0 baseline.
*
*/
Pour le niveau de la procédure, je trouve agréable de réaliser
des espèces de cartouches permettant de découper visuellement un listing en
ses différentes procédures, comme ceci par exemple :
/******************************************************************************/
/* */
/* strcpy */
/* */
/* But: */
/* copie une chaîne dans une autre */
/* */
/* Interface: */
/* s1 : chaîne destination */
/* s2 : chaîne source */
/* */
/******************************************************************************/
En ce qui concerne le niveau groupe d'instruction, il est classique de faire
une mise en page comme dans l'exemple suivant tiré du source de dvips
1.3 :
/*
* If nothing above worked, then we get desperate. We attempt to
* open the stupid font at one of a small set of predefined sizes,
* and then use PostScript scaling to generate the correct size.
*
* We much prefer scaling up to scaling down, since scaling down
* can omit character features, so we try the larger sizes first,
* and then work down.
*/
Pour le niveau déclaration ou instruction, on commentera sur la même ligne.
Exemple tiré du source du compilateur GNU CC :
char *name; /* Function unit name. */
struct function_unit *next; /* Next function unit. */
int multiplicity; /* Number of units of this type. */
int simultaneity; /* Maximum number of simultaneous insns
on this function unit or 0 if unlimited. */
struct range ready_cost; /* Range of ready cost values. */
struct range issue_delay; /* Range of issue delay values. */
