Les commentaires

0

Cette subsection est EXHAUSTIVE et CONFORME a ANSI C sauf pour le pb a la ligne MIS EN COMMENTAIRE (car on ne parle pas des constantes caractères de plusieurs caractères)

References : K&R : A2.2 ; ANSI C : 6.1.9 La suite du chapitre est formée de recommandations de mon cru

$\bullet$

Syntaxe :
Les commentaires débutent par /* et se terminent par */. Exemple :

/*   Ceci est un commentaire   */

Toute occurrence de /* est interprétée comme le début d'un commentaire sauf dans une chaîne littérale, ou un commentaire (les commentaires ne peuvent donc pas être imbriqués).

$\bullet$

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, 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'instructions : 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.
 */

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 : ifundefinedmobilemode

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.  */