Les commentaires

     

$\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, 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  :

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

Attention

$\bullet$

L'erreur classique avec les commentaires est d'oublier la séquence fermante */. Dans ce cas, le compilateur va considérer que le commentaire se poursuit jusqu'à la fin du prochain commentaire : et ceci peut ne pas générer d'erreur syntaxique. Exemple :
instruction
/* premier commentaire
instruction
...
instruction
/* second commentaire */
instruction

On voit que dans ce cas, tout un ensemble d'instructions sera ignoré par le compilateur sans générer le moindre message d'erreur .

$\bullet$

Un commentaire ne peut pas contenir un commentaire, il n'est donc pas possible de mettre en commentaire un morceau de programme comportant déjà des commentaires.