Bonnes pratiques de codage en langage C

Il existe de nombreuses façons de présenter le code C. Certaines sont plus prisées que d'autres, et je n'entrerai pas dans ce débat. Par contre, il est important, une fois qu'on a décidé de ce qui était « bien », de s'y tenir.

Tout le code présenté sur ce site observe des règles homogènes de présentation. Un moyen simple d'y parvenir est d'utiliser un outil unique pour la mise en page (indentation), tel que GNU Indent. Cet outil dispose de nombreux paramètres que personnellement j'ai fixés une fois pour toutes, et qui confèrent à mes codes sources une certaine unité.

indent -bli0 -npsl -i3 -ts0 -sob

Il est fortement recommandé d'utiliser un éditeur qui permet de remplacer les tabulations par des espaces (l'idéal étant que le nombre soit programmable). En effet, l'effet d'une tabulation n'est pas uniforme, alors que celui d'un espace l'est certainement davantage (à part en HTML, mais il y a des contournements possibles).

Le langage C, dans sa version normalisée ISO-1990, ne supporte que les commentaires de type /* comment */. L'imbrication des commentaires n'est pas autorisée.

Il est préférable d'éviter de placer des commentaires en bout de ligne. En effet, certains périphériques ou applications limitent la largeur visible du texte à moins de 80 colonnes. Ce serait dommage de se priver de commentaires qui peuvent être utiles. Il est donc recommandé de placer ses commentaires au-dessus de la portion de code à commenter.

/* compteur */
int cpt ;

Si un commentaire doit utiliser plusieurs lignes, il est recommandé d'utiliser la présentation 'ouverte', qui facilite la maintenance, tout en préservant la lisibilité. Exemple de forme minimale :

/* Ce compteur doit être initialise
   avant utilisation */
int cpt ;

S'il faut isoler provisoirement une portion de code, le mieux est de ne pas utiliser les commentaires (il pourrait y avoir des commentaires imbriqués), mais plutôt les directives du préprocesseur : #ifdef .. #endif ou #if .. #endif

#if 0
  /* Compteur */
  int cpt ;
#endif

Le moins possible !

Le principe est de ne commenter que ce qui apporte un supplément d'information. Il est d'usage d'utiliser en priorité l'autodocumentation, c'est-à-dire un choix judicieux des identificateurs qui fait que le code se lit 'comme un livre'…

L'outil avec lequel un programmeur passe probablement le plus de temps est son éditeur de texte. Il entre dans une part importante de la productivité du programmeur et de la présentation du code.

Je n'entrerai évidemment pas dans le débat futile Vi/Emacs, car je mets tout le monde d'accord avec UltraEdit32 ! En fait peu importe, pourvu qu'il dispose au moins des fonctions suivantes :

• police à chasse fixe ;
• coloration syntaxique ;
• la touche TAB produit des espaces (programmable, pour moi, c'est 3) ;
• édition en mode colonne ;
• annulation ;
• copie de sauvegarde ;
• patrons avec fonctions de base comme le nom du fichier et la date de création ;
• possibilité d'ajouter des outils externes pour compléter ce qui manque.

Il est couramment admis que les constantes 'vraies' (macros, énumérations) doivent être écrites en majuscules. Les variables qualifiées const seront écrites comme des variables.

L'identificateur dépend du contexte. Il sert souvent à définir les valeurs des propriétés d'un objet (valeurs particulières, états, etc.). Il est recommandé d'utiliser un préfixe qui relie les constantes qui qualifient une même propriété.

  /*
  * Valeurs possibles de l'état du voyant
  *
  * OFF   : éteint
  * ON    : allume fixe
  * BLINK : clignotant
  */
  enum
  {
    VOYANT_STS_OFF,
    VOYANT_STS_ON,
    VOYANT_STS_BLINK,
 
    VOYANT_STS_NB
  };

Il y a deux façons de créer des valeurs constantes. Avec une macro ou avec une énumération.

Pour les constantes numériques de type int, il est recommandé d'utiliser les enum, qui présentent des avantages comme le typage, la numérotation automatique, ou l'interprétation textuelle automatique dans les débogueurs.

Pour les constantes numériques des autres types (long, unsigned, etc.) et les chaînes, il n'y a pas le choix, il faut utiliser les macros. Ne pas oublier les qualificateurs de macros pour les valeurs numériques autres que int : Suffixes de macros numériques u ou U unsigned :

Ne pas oublier non plus que pour qu'une constante soit de type double, au moins un des membres doit être de type double, donc comprendre un '.' dans son expression :

  #define PI (22/7)

est un entier qui vaut 3.

  #define PI (22/7.0)

est un double qui vaut environ 3.14.

Il est d'usage d'utiliser les minuscules. Il est recommandé d'utiliser des suffixes tels que :

Il est d'usage d'utiliser les minuscules.

Il est un principe général de bonne conception qui veut que la longueur des identificateurs des objets et des fonctions soit proportionnelle à leur portée.

Les variables introduisent en plus la notion de durée de vie (duration). Il est bon qu'au premier coup d'œil, on sache exactement à quoi on a affaire. Il est bon de pouvoir aussi identifier rapidement les variables en fonction de leurs propriétés. Les plus remarquables sont :

• simple (plain) ;
• pointeur ;
• tableau statique ;
• tableau dynamique ;
• chaîne de caractères.

Il est donc recommandé d'utiliser les préfixes suivants :

et en ce qui concerne la durée de vie et la portée :

Il est d'usage d'utiliser les minuscules. Il existe des cas où l'on a besoin de deux mots pour nommer une fonction. Il n'est évidemment pas question d'accoler ces deux mots en minuscule, car le code serait vite illisible. Il existe deux pratiques répandues :

• coller les mots en mettant une majuscule au début de chaque mot :

OuvrirFichier()

ou (variante «à-la-Java») à partir du 2e mot :

ouvrirFichier()

• séparer les mots en mettant un souligné (underscore) entre chaque mot.

ouvrir_fichier()

C'est une question de goût, le principal est d'être clair et cohérent. La seconde méthode a ma préférence.

Pour une fonction, on choisit plutôt un identificateur qui exprime une action (verbe, verbe + substantif).

• inclusion des en-têtes (.h) nécessaires ;
• définition des macros privées ;
• définition des constantes privées ;
• définition des types privés ;
• définition des structures privées ;
• définition des variables globales privées ;
• définition des fonctions privées ;
• définition des fonctions publiques ;
• définition des variables globales publiques.

Voici par exemple, une liste de séparateurs utilisés pour structurer des fichiers sources :

  /* macros ============================================================== */
  /* constants =========================================================== */
  /* types =============================================================== */
  /* structures ========================================================== */
  /* private variables =================================================== */
  /* private functions =================================================== */
  /* internal public functions =========================================== */
  /* entry points ======================================================== */
  /* public variables ==================================================== */

• un fichier d'en-tête doit être protégé contre les inclusions multiples dans la même unité de compilation ;
• un fichier d'en-tête doit être autonome^[1] ;
• un fichier d'en-tête ne doit inclure que le strict nécessaire à son autonomie.

^[1] Pour s'en assurer, lors des tests de l'implémentation correspondante, le placer en ^1re position et ajouter ce qu'il manque dedans.

• inclusion des headers nécessaires et suffisants ;
• définition des macros publiques ;
• définition des constantes publiques ;
• définition des types publics ;
• définition des structures publiques ;
• déclaration des fonctions publiques ;
• déclaration des variables globales publiques ;
• [C99] définition des fonctions publiques inline.

Voici par exemple, une liste de séparateurs utilisés pour structurer des fichiers d'en-tête :

  /* macros ============================================================== */
  /* constants =========================================================== */
  /* types =============================================================== */
  /* structures ========================================================== */
  /* internal public functions =========================================== */
  /* entry points ======================================================== */
  /* public variables ==================================================== */
  /* inline public functions  ============================================ */

À l'origine, on a un fichier avec main() (par exemple main.c, comme ça, on voit tout de suite de quoi on parle). main() est le point d'entrée (unique) de ce module. On peut donc écrire :

/* main.c */
#include 
 
/* entry points ======================================================== */
 
int main (void)
{
   puts ("hello world");
 
   return 0;
}

Le programme évoluant, on a maintenant une fonction privée (static) :

/* main.c */
#include 
 
/* private functions =================================================== */
 
static void hello(void)
{
   puts ("hello world");
}
 
/* entry points ======================================================== */
 
int main (void)
{
   hello();
 
   return 0;
}

Nouvelle évolution, on crée un bloc fonctionnel (BF) hello composé pour le moment d'une seule fonction. On retrouve donc la structure habituelle avec trois fichiers :

#ifndef H_HELLO
#define H_HELLO
/* hello.h */
 
/* entry points ======================================================== */
 
void hello(void);

/* hello.c */
#include "hello.h"
#include 
 
/* entry points ======================================================== */
 
void hello(void)
{
   puts ("hello world");
}

/* main.c */
#include "hello.h"
 
/* entry points ======================================================== */
 
int main (void)
{
   hello();
 
   return 0;
}

On fait dans le luxe et on décompose la fonction hello() en plusieurs petites fonctions (un peu théorique, mais c'est pour montrer le principe).

/* hello.c */
#include "hello.h"
#include 
 
/* private functions =================================================== */
 
static void h(void)
{
   printf ("hello");
}
 
static void w(void)
{
   printf ("world");
}
 
static void spc(void)
{
   putchar (' ');
}
 
static void eol(void)
{
   putchar ('\n');
}
 
/* entry points ======================================================== */
 
void hello(void)
{
   h();
   spc();
   w();
   eol();
}

Le reste (interface, allocation) est inchangé.

Attention, étape ultime et subtile.

Le fichier d'implémentation de hello est devenu tellement gros qu'il nécessite lui-même un découpage. Il va donc falloir distinguer ce qui est accessible à l'utilisateur de hello (les points d'entrées) et les fonctions 'internes', c'est-à-dire connues de hello mais pas de l'application, d'où cette distinction, qui se traduit aussi par des headers distincts :

/* hellotools.c */
#include "hellotools.h"
#include 
 
/* internal public functions =========================================== */
void hello_spc(void)
{
   putchar (' ');
}
 
void hello_eol(void)
{
   putchar ('\n');
}

#ifndef H_HELLOTOOLS
#define H_HELLOTOOLS
/* hellotools.h */
 
/* internal public functions =========================================== */
void hello_spc(void);
void hello_eol(void);
 
#endif

/* hello.c */
#include "hellotools.h"
#include "hello.h"
 
#include 
 
/* private functions =================================================== */
static void h(void)
{
   printf ("hello");
}
 
static void w(void)
{
   printf ("world");
}
 
/* entry points ======================================================== */
void hello(void)
{
   h();
   hello_spc();
   w();
   hello_eol();
}

Cela revient à créer plusieurs niveaux de visibilité…

Les fichiers d'en-tête pouvant être inclus dans des fichiers sources, comme dans des fichiers d'en-tête, et ce, dans un ordre non spécifié, il est indispensable de se prémunir contre les risques d'inclusions multiples dans la même unité de compilation.

  #ifndef IDENTIFICATEUR
  #define IDENTIFICATEUR
 
  /* zone protégée contre les inclusions multiples */
 
  #endif /* guard */

Le principe de protection étant basé sur la définition d'une macro, cette macro doit être unique afin d'éviter les protections abusives.

Personnellement, j'utilise le format suivant :

  H_<initials>_<file>_<date>
  initials ::= En majuscule : initiales du développeur, nom de la société, etc.
  file     ::= En majuscule : nom du fichier (sans l'extension)
  date     ::= <year><month><day><hour><minute><second>
  year    ::= année (0000-9999)
  month   ::= mois (01-12)
  day     ::= jour (01-31)
  hour    ::= heure (00-23)
  minute  ::= minute (00-59)
  second  ::= seconde (00-59)

Par exemple :

  H_ED_EXEMPLE_20040529115235