star-style

star-c.7 (40476B)

---

 .\" Copyright (C)  2026  |Méso|Star> (contact@meso-star.com)
 .\"
 .\" Ce fichier fait partie de Star-Style
 .\"
 .\" Star-Style est un logiciel libre ; vous pouvez le redistribuer ou le
 .\" modifier suivant les termes de la GNU General Public License telle
 .\" que publiée par la Free Software Foundation ; soit la version 3 de
 .\" la licence, soit (à votre gré) toute version ultérieure.
 .\"
 .\" Star-Style est distribué dans l'espoir qu'il sera utile, mais SANS
 .\" AUCUNE GARANTIE ; sans même la garantie tacite de QUALITÉ MARCHANDE
 .\" ou d'ADÉQUATION à UN BUT PARTICULIER. Consultez la GNU General
 .\" Public License pour plus de détails.
 .\"
 .\" Vous devez avoir reçu une copie de la GNU General Public License en
 .\" même temps que Star-Style ; si ce n'est pas le cas, consultez
 .\" <http://www.gnu.org/licenses>.
 .Dd July 13, 2026
 .Dt STAR-C 7
 .Os
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .Sh NOM
 .Nm star-c
 .Nd guide d'écriture de code en C
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .Sh DESCRIPTION
 Ce document décrit les conventions d'écriture des programmes C
 distribués par |Méso|Star>.
 Ces recommandations sont données à titre indicatif, et reste
 subordonnées aux pratiques effectivement retenues dans chaque
 projet ; le plus important étant d'en conserver la cohérence.
 Si bien que s'il appartient aux co-auteurs d'un projet de prendre
 certaines libertés quant à ce guide de style, toute participation à son
 développement devra alors s'efforcer de respecter le style d'écriture du
 projet, avant les préférences listées ici.
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .Sh LE CONTENU D'UN PROJET
 En suivant le philosophie UNIX, assurer un jeu de
 fonctionnalités par programme aussi ramassé que possible de
 sorte à ce que sa mise en oeuvre et son interface restent
 simples et ciselées.
 L'objet étant d'assurer sa robustesse, son efficacité et sa
 modularité qui dépendent d'abord de sa
 .Em relation
 à un écosystème logiciel qui le dépasse, bien avant son catalogue de
 fonctionnalités ou ses prouesses de mise en oeuvre.
 .Pp
 Le périmètre étroit de chaque programme se retrouve dès lors dans la
 structure du projet auquel il appartient, dont le contenu est alors
 simple et peu hiérarchisé car comptant en définitive peu de fichiers.
 .Pp
 La structure type du répertoire d'un projet est :
 .Bd -literal -offset Ds
 README.md
 COPYING
 config.mk
 Makefile
 src/foo.h
 src/foo.c
 src/foo_bar.c
 doc/foo_bar.1
 doc/foo.3
 .Ed
 .Pp
 Avec :
 .Bl -dash -compact
 .It
 .Pa README.md
 le fichier qui donne le premier niveau d'informations sur le projet ;
 .It
 .Pa COPYING
 la license du projet qui liste ses conditions légales d'utilisation ;
 .It
 .Pa config.mk
 et
 .Pa Makefile
 les fichiers du système de génération automatique ;
 .It
 .Pa src/
 le répertoire qui contient les codes source du projet ;
 .It
 .Pa doc/
 le répertoire qui stocke sa documentation.
 .El
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .Sh LE LANGAGE C
 Utiliser le langage
 .Em C89
 .Pq ANSI X3.159-1989
 aussi appelé C90
 .Pq ISO/IEC 9899:1990 ,
 les deux étant équivalent.
 .Pp
 Cette norme est plus épurée que celle qui lui succède à savoir le C99
 .Pq ISO SO/IEC 9899:1999 ,
 ce qui en fait un dialecte C à la fois plus simple, plus portable et
 plus consistant.
 Par exemple en ne proposant qu'une seule façon d'écrire les commentaires,
 et en interdisant de mélanger du code avec la définition de variables.
 .\""""""""""""""""""""""""""""""""""
 .Ss Le standard POSIX
 Ajouter le support du standard POSIX pour les seuls fichiers qui en ont
 besoin, pour notamment pouvoir utiliser des fonctions de la bibliothèque
 C standard sinon indisponibles via la seule norme du langage retenue.
 .Pp
 Pour ce faire, définir la macro
 .Sy _POSIX_C_SOURCE
 tout en haut du fichier C concerné, avant la moindre directive
 d'inclusion.
 Par exemple, pour utiliser le standard POSIX.1-2001 :
 .Bd -literal -offset Ds
 #define _POSIX_C_SOURCE 200112L
 .Ed
 .Pp
 Sous GNU/Linux, se référer à
 .Xr feature_test_macros 7
 pour une description exhaustive des macros utilisées pour activer le jeu
 de fonctionnalités d'un standard donné.
 .Pp
 L'utilisation d'un C enrichi du standard POSIX n'est ainsi utilisé que
 sur les seuls fichiers qui en explicite le besoin ; le C89 restant le
 langage utilisé partout ailleurs.
 Dans un même souci de portabilité, retenir la première version du
 standard POSIX à partir de laquelle la fonctionnalité recherchée est
 apparue.
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .Sh LA STRUCTURE D'UN FICHIER SOURCE
 Suivre une seule et même structure pour tous les fichiers
 sources, qu'ils soient des fichiers d'en-tête
 .Pq fichiers Ql *.h
 ou des unités de compilation
 .Pq fichiers Ql *.c .
 Un seul schéma de lecture participant à la clarté du code source.
 .Pp
 Ci-après sont listées les différentes parties d'un fichier source :
 .Bl -enum
 .\""""""""""""""""""""""""""""""""""
 .It
 Un commentaire avec l'avis de copyright et les avis de licence du
 programme
 .Pq section Sx L'AVIS DE COPYRIGHT ET LES AVIS DE LICENCE Ns
  ;
 .\""""""""""""""""""""""""""""""""""
 .It
 La définition d'une macro qui ajoute au langage C du fichier le support
 d'un standard POSIX
 .Pq section Sx LE LANGAGE C Ns
  ;
 .\""""""""""""""""""""""""""""""""""
 .It
 Pour un fichier d'en-tête, l'ouverture d'un garde-fou évitant sa double
 inclusion.
 Il est fermé en toute fin du fichier
 .Pq partie 10 Ns
  :
 .Bd -literal -offset Ds
 #ifndef FOO_H
 #define FOO_H
 .Ed
 .Pp
 Le nom de la macro testée puis définie est celui du fichier d'en-tête,
 suffixé par
 .Ql _H
 en référence à l'extension
 .Ql .h
 du fichier.
 Dans l'exemple qui précède, le garde-fou concerne donc le fichier
 .In foo.h .
 La convention de nommage est sinon celle utilisée pour n'importe quelle
 macro
 .Pq section Sx LE NOMMAGE .
 .\""""""""""""""""""""""""""""""""""
 .It
 L'inclusion des fichiers d'en-tête requis par le fichier source ;
 .Pq section Sx LES FICHIERS D'EN-TÊTE Ns
  ;
 .\""""""""""""""""""""""""""""""""""
 .It
 La définition des macros
 .Pq section Sx LES MACROS Ns
  ;
 .\""""""""""""""""""""""""""""""""""
 .It
 La déclaration anticipée des types structurés :
 .Bd -literal -offset Ds
 /* Type structurés externes au programme */
 struct plugh;
 struct quux;
 struct xyzzy;
 
 /* Types structurés définis ailleurs dans le programme */
 struct bar;
 struct foo;
 .Ed
 .\""""""""""""""""""""""""""""""""""
 .It
 La définition des constantes symboliques de type
 .Vt enum
 .Pq section Sx LES CONSTANTES SYMBOLIQUES Ns
  ;
 .\""""""""""""""""""""""""""""""""""
 .It
 La définition des types structurés et de leur(s) constante(s)
 .Pq section Sx LES STRUCTURES Ns
  ;
 .\""""""""""""""""""""""""""""""""""
 .It
 La déclaration et définition des fonctions
 .Pq section Sx LES FONCTIONS .
 Dans l'ordre qui suit :
 .Pp
 .Bl -tag -compact -width a.
 .It a.
 la déclaration des fonctions ;
 .It b.
 la définition des fonctions statiques ;
 .It c.
 pour les unités de compilation, la définition des fonctions.
 .El
 .\""""""""""""""""""""""""""""""""""
 .It
 Pour les fichiers d'en-tête, la fin du garde-fou ouvert en 3 pour éviter
 la double inclusion du contenu du fichier.
 .El
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .Sh LA LONGUEUR DES LIGNES
 La longueur maximale recommandée pour une ligne est de
 .Em 80
 caractères.
 .Pp
 Ce nombre, standardisé par les cartes perforées et les terminaux des
 années 1970, vise aussi à faciliter la lecture du code source en
 s'insipirant des conventions d'édition.
 Pour un texte imprimé avec une taille de police entre 9 à 12 points et
 un inter-ligne d'un caractère, un confort de lecture est assuré dès
 lors que chaque ligne compte entre 60 et 75 caractères.
 Une proximité avec les 80 caractères retenus, que l'indentation
 des sources vient encore renforcer.
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .Sh L'AVIS DE COPYRIGHT ET LES AVIS DE LICENCE
 Utiliser la licence libre GPLv3+ qui, en tant que licence copyleft,
 défend la copie, l'étude et la modification libres du programme ainsi
 licencié, et de ses évolutions.
 .Pp
 Ajouter une copie de la licence à la racine du projet, dans un fichier
 texte nommé
 .Pa COPYING
 .Pq voir Lk https://www.gnu.org/licenses/gpl-3.0.txt .
 .Pp
 Lister en commentaire l'avis de copyright et la déclaration
 d'autorisation de copie en en-tête de
 .Em chaque
 fichier source.
 .Pp
 Chaque copyright débute par le mot
 .Ql Copyright ,
 en anglais, suivi des 3 caractères
 .Ql (C) ,
 traduction ASCII du caractère © qui, quant à lui, peut ne pas être
 supporté par les jeu de caractères utilisé.
 Lister ensuite les années pour lesquelles une version du programme a été
 publiée, avant le nom de l'auteur(e) ayant participé(e) à
 sa réalisation.
 Conclure chaque avis par l'adresse de contact de l'auteur(e), donnée
 entre parenthèses.
 .Pp
 Sauter une ligne après l'avis de copyright et ajouter la déclaration
 autorisant la copie telle que donnée par la Fondation pour le logiciel
 libre.
 Utiliser l'avis de copyright en anglais qui, au contraire de sa
 traduction française, revêt une signification juridique.
 .Pp
 L'en-tête type d'un fichier source du programme
 .Ql Foo
 est :
 .Bd -literal -offset Ds
 /* Copyright (C) 2016-2018, 2020, 2022, 2026
  *   Jeanne Lambda (jeanne.lambda@courriel.fr)
  * Copyright (C) 2017, 2019 Jean Untel (juntel@courriel.fr)
  * Copyright (C) 2024 |Méso|Star> (contact@meso-star.com)
  *
  * This file is part of Foo.
  *
  * Foo is free software: you can redistribute it and/or
  * modify it under the terms of the GNU General Public License
  * as published by the Free Software Foundation, either
  * version 3 of the License, or (at your option) any later
  * version.
  *
  * Foo is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty
  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
  * the GNU General Public License for more details.
  *
  * You should have received a copy of the GNU General Public
  * License along with Foo. If not, see
  * <https://www.gnu.org/licenses/>. */
 .Ed
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .Sh L'INDENTATION
 Indenter le texte par 2 espaces.
 La mise en page du texte, taille de ligne comprise, est ce faisant
 indépendante de la taille d'une tabulation.
 .Pp
 Les auteurs sont encouragés à configurer leur éditeur pour
 qu'il développe chaque caractère tabulation en 2 espaces
 .Pq section Sx FICHIERS .
 Et ainsi continuer à utiliser la touche tabulation pour l'indentation.
 .Pp
 Limiter l'indentation à 2 caractères, contre 8 pour le standard de facto
 des tabulations, laisse plus d'espace aux différents niveaux
 d'indentation, dès lors moins contraints par la limite du nombre de
 caractères par ligne
 .Pq section Sx LA LONGUEUR DES LIGNES .
 Néanmoins, un niveau d'indentation supérieur à 3 est aussi le signe d'un
 déficit de structure dans l'écriture du programme.
 Les 2 espaces retenus pour indenter le code n'est donc pas une
 incitation à aller au delà de 3 niveaux d'indentation sous prétexte de
 disposer de plus d'espace par niveau.
 .Pp
 Indenter le contenu de chaque bloc
 .Pq section Sx LES BLOCS .
 Pour la directive
 .Ql switch ,
 indenter chaque
 .Ql case
 ainsi que leur contenu :
 .Bd -literal -offset Ds
 switch (opt) {
   case 'e':
     errno = 0;
     epsilon = strtod(optarg, NULL);
     if (errno != 0) err = 1;
     break;
   case 'h':
     printf("usage: foo [-hov]\en");
     break;
   case 'o':
     output = optarg;
     break;
   case 'v':
     verbose += (verbose < 3);
     break;
   default:
     err = 1;
     break;
 }
 .Ed
 .Pp
 Motiver l'utilisation de plusieurs instructions par ligne par
 l'expressivité du code en résultant, qu'une écriture resserrée viendrait
 renforcer :
 .Bd -literal -offset Ds
 if (x == NULL || y == NULL) { err = 1; goto error; }
 x[0] = 1.0; x[1] = 0.0;
 y[0] = 0.0; y[1] = 1.0;
 .Ed
 .Pp
 Ne sauter au plus qu'une ligne.
 Ne pas laisser d'espace en fin de ligne et supprimer les lignes vides
 en fin de fichier.
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .Sh LES COMMENTAIRES
 Utiliser des commentaires dès lors que la seule expressivité serrée du
 code ne permet pas d'exprimer l'entièreté du discours que les sources
 doivent rendre compte, ou la logique qu'il met effectivement en oeuvre.
 .Pp
 Si un commentaire occupe plusieurs lignes, ajouter un caractère
 .Ql *
 en début de ligne, aligné avec le caractère
 .Ql *
 de la ligne qui précède :
 .Bd -literal -offset Ds
 /* Valeurs de hachage initiales, à savoir les 32 premiers bits
  * de la partie fractionnaire des racines carrées des 4 premiers
  * nombres premiers (2, 3, 5 et 7) */
 state[0] = 0x6a09e667;
 state[1] = 0xbb67ae85;
 state[2] = 0x3c6ef372;
 state[3] = 0xa54ff53a;
 .Ed
 .Pp
 Les commentaires servent aussi à structurer la lecture du code source.
 Que ce soit à l'échelle des instructions, par un commentaire
 .Dq chapeau
 qui résume la séquence de code qui suit :
 .Bd -literal -offset Ds
 /* Enregistrer le résultat */
 ((uint32_t*)hash)[0] = big_endian_32(state[0]);
 ((uint32_t*)hash)[1] = big_endian_32(state[1]);
 ((uint32_t*)hash)[2] = big_endian_32(state[2]);
 ((uint32_t*)hash)[3] = big_endian_32(state[3]);
 .Ed
 .Pp
 ou à l'échelle du fichier, où les commentaires servent alors de
 séparateur entre ses différentes sections
 .Pq voir Sx LA STRUCTURE D'UN FICHIER SOURCE .
 Dans ce cas, encadrer le commentaire par deux ligne de caractères
 .Ql *
 qui débute ou se termine par le caractère
 .Ql /
 si, respectivement, la ligne précède ou suit l'intitulé de la section :
 .Bd -literal -offset Ds
 /***********************************************************
  * Définition des fonctions utilitaires
  **********************************************************/
 static void
 foo(uint32_t bar[4], const char baz[64])
 {
   ...
 }
 .Ed
 .Pp
 À noter que dans l'exemple qui précède, la taille des lignes
 d'encadrement est limitée par des contraintes d'édition de la présente
 page de manuel.
 Dans un fichier source, étendre ces lignes pour qu'elles occupent la
 longueur maximale recommandée pour une ligne, à savoir 80 caractères.
 .Pp
 Pour expliciter le contexte général d'un fichier, en terme d'utilisation
 ou d'architecture logicielle, insérer un commentaire en en-tête du
 fichier en laissant les caractères d'ouverture ou de fermeture de
 commentaires sur une ligne séparée :
 .Bd -literal -offset Ds
 /*
  * Interface de programmation des tableaux extensibles.
  * Cette structure de données peut être utilisée avec des
  * types de données qui ne nécessitent pas de processus
  * d'initialisation ou de libération et qui peuvent être
  * copiés bit à bit
  */
 .Ed
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .Sh LES FICHIERS D'EN-TÊTE
 Inclure les fichiers d'en-tête dans l'ordre qui suit :
 .Bl -enum -compact
 .It
 les en-têtes locaux au programme ;
 .It
 les en-têtes des dépendances du programme ;
 .It
 les en-têtes systèmes et ceux de la bibliothèque C standard.
 .El
 .Pp
 Les fichiers d'en-tête sont ainsi inclus dans l'ordre décroissant de
 leur niveau d'abstraction.
 Cet ordre participe à garantir que chaque fichier d'en-tête inclus les
 en-têtes dont il a lui même besoin, indépendamment des directives
 d'inclusion qui précèdent sa propre inclusion.
 Si ce n'est pas le cas, la compilation pourra échouer, symptôme qu'un
 des fichiers d'en-tête n'est pas auto-consistant.
 .Pp
 Dans chaque groupe, trier les directives d'inclusion par ordre
 alphabétique des fichiers d'en-tête.
 Si besoin, ajouter un commentaire court, sur la même ligne que la
 directive d'inclusion, qui explicite la raison pour laquelle la fichier
 est inclus.
 .Bd -literal -offset Ds
 #include "bar.h"
 #include "foo.h"
 #include "qux.h"
 
 #include <baz.h>
 
 #include <float.h> /* FLT_MAX */
 #include <stdio.h>
 .Ed
 .Pp
 S'efforcer de n'inclure que les seuls fichiers d'en-tête
 réellement nécessaires au fichier ;
 par exemple par une déclaration anticipée des types structurés à
 la place d'inclure des en-têtes dans le seul but de déclarer lesdits
 types.
 Un enjeu a considérer avec d'autant plus d'attention que le fichier
 concerné par les inclusions est lui même un fichier d'en-tête, par
 conséquent amené à être lui même inclus.
 L'objet étant de limiter autant que possible le nombre de fichiers
 inclus par unité de compilation, pour limiter les accès disque et ainsi
 réduire les temps de compilation.
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .Sh LA VISIBILITÉ DES SYMBOLES
 Par défaut, n'exposer aucun symbole
 .Po
 option
 .Fl fvisibility=hidden
 du compilateur
 .Xr gcc 1
 .Pc ,
 à l'exception de ceux de l'interface de programmation d'une
 bibliothèque.
 .\""""""""""""""""""""""""""""""""""
 .Ss Les symboles d'interface
 Privilégier l'écriture d'un seul fichier d'en-tête pour exposer
 l'interface de programmation d'une bibliothèque.
 Y définir une macro qui exporte les symboles qu'elle déclare dès lors
 que ce fichier d'en-tête est inclus par une unité de compilation de la
 bibliothèque.
 Et qui se contente d'importer ces mêmes symboles si ce même fichier est
 inclus par un programme tiers :
 .Bd -literal -offset Ds
 #include <rsys/rsys.h>
 
 #if defined(FOO_SHARED_BUILD)
   #define FOO_API extern EXPORT_SYM
 else
   #define FOO_API extern IMPORT_SYM
 #endif
 .Ed
 .Pp
 Avec :
 .Bl -dash -compact
 .It
 .Sy FOO_SHARED_BUILD
 une macro définie uniquement à la compilation de la bibliothèque
 .Po
 option
 .Fl DFOO_SHARED_BUILD
 du compilateur C
 .Pc Ns
  ;
 .It
 .Sy EXPORT_SYM
 et
 .Sy IMPORT_SYM
 des directives définies dans la bibliothèque
 .Ql RSys .
 Elles enrichissent le langage C d'une gestion explicite de la visibilité
 des symboles.
 .El
 .Pp
 Utiliser cette macro à la déclaration des variables et constantes
 d'interfaces :
 .Bd -literal -offset Ds
 /* Variables globales de l'interface de programmation */
 FOO_API const struct foo foo_plugh;
 FOO_API const struct foo foo_xyzzy;
 .Ed
 .Pp
 Déclarer le prototype des fonctions d'interface entre les directives
 .Sy BEGIN_DECLS
 et
 .Sy END_DECLS ,
 elles aussi définies dans la bibliothèque
 .Ql RSys
 .Pq en-tête In rsys/rsys.h .
 Ainsi, le fichier d'en-tête peut être inclus par un programe C++ :
 .Bd -literal -offset Ds
 BEGIN_DECLS
 
 FOO_API void
 foo_bar
   (int i,
    int* j);
 
 FOO_API int
 foo_qux
   (double d,
    int i);
 
 END_DECLS
 .Ed
 .\""""""""""""""""""""""""""""""""""
 .Ss Les symboles internes partagés
 Pour les fichiers d'en-tête internes au programme, utiliser la directive
 .Sy LOCAL_SYM ,
 définie dans le fichier
 .In rsys/rsys.h
 de la bibliothèque
 .Ql RSys ,
 pour déclarer les variables globales et prototypes de fonctions.
 Ainsi leur symbole n'est pas exposé à l'extérieur du programme.
 .Bd -literal -offset Ds
 #include <rsys/rsys.h>
 
 extern LOCAL_SYM char bar[128];
 
 extern LOCAL_SYM void
 quux
   (char* tab,
    size_t length);
 .Ed
 .Pp
 Cette directive est redondante si le compilateur est configuré pour
 masquer par défaut tous les symboles
 .Po
 option
 .Fl fvisibility=hidden
 de
 .Xr gcc 1
 .Pc .
 Utiliser
 .Sy LOCAL_SYM
 permet néanmoins de s'exonérer de cet a priori, tout en uniformisant
 les déclarations des fonctions et variables en explicitant pour chaque
 déclaration la visibilité du symbole associé.
 .\""""""""""""""""""""""""""""""""""
 .Ss Les symboles internes à une unité de compilation
 Utiliser le mot clé
 .Ql static
 pour déclarer des variables, constantes, et fonctions visibles
 uniquement au sein d'une unité de compilation.
 .Pp
 C'est notamment le cas des constantes symboliques structurées :
 .Bd -literal -offset Ds
 struct foo {
   int bar;
   int qux;
 };
 static const struct foo FOO_DEFAULT = {1, 0};
 .Ed
 .Pp
 Mais aussi des fonctions utilitaires, qu'elles soient
 propres à un fichier C, ou définies dans un fichier d'en-tête.
 .Bd -literal -offset Ds
 static void
 hello(void)
 {
   printf("Hello, world!\en");
 }
 .Ed
 .Pp
 Ces fonctions peuvent en plus être déclarées avec la directive
 .Sy INLINE ,
 définie dans l'en-tête
 .In rsys/rsys.h
 de la bibliothèque
 .Ql RSys ,
 pour suggérer au compilateur de substituer l'appel de la fonction par le
 corps de celle-ci, de sorte à éviter le surcoût de l'appel.
 Cette directive est équivalente au mot clé
 .Ql inline
 du C99, indisponible dans le dialecte C retenu
 .Pq section Sx LE LANGAGE C .
 .Bd -literal -offset Ds
 static INLINE void
 foo(void)
 {
   printf("bar\en");
 }
 .Ed
 .Pp
 Limiter la directive
 .Sy INLINE
 aux fonctions élémentaires, destinées à être appelées fréquemment et
 dont le coût de l'appel pourrait alors s'avérer significatif.
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .Sh LES BLOCS
 Ouvrir chaque bloc sur la même ligne que la directive qui en est à
 l'origine
 .Po
 .Ql do ,
 .Ql enum
 .Ql for ,
 .Ql if ,
 .Ql struct ,
 .Ql switch ,
 .Ql union ,
 .Ql while
 .Pc ,
 en séparant par un espace la fin de la directive et le caractère
 .Ql {
 qui marque l'ouverture du bloc :
 .Bd -literal -offset Ds
 if (foo) {
   bar();
   qux();
 }
 .Ed
 .Pp
 Exception faite des fonctions, ou le bloc associé est ouvert sur la
 ligne qui suit :
 .Bd -literal -offset Ds
 static void
 foo(void)
 {
   printf("bar\en");
 }
 .Ed
 .Pp
 Fermer un bloc sur une ligne à part sauf s'il est suivi d'une nouvelle
 structure de contrôle associée à la précédente
 .Po
 .Ql if else ,
 .Ql do while
 .Pc .
 Dans ce cas, ajouter la nouvelle instruction sur la même ligne que celle
 utilisée pour fermer le bloc, en la séparant du caractère
 .Ql }
 par un espace.
 .Pp
 Aligner la fermeture du bloc à l'indentation de sa directive, ou, dans
 le cas de directives qui se suivent, à l'indentation de la première
 directive à l'origine des blocs successifs :
 .Bd -literal -offset Ds
 if (foo) {
   bar();
 } else {
   qux();
 }
 .Ed
 .Pp
 Écrire sur une seule ligne une directive et les opérations qu'elle
 contrôle que si la clarté du code n'en est pas impactée.
 Dans ce cas, l'ouverture et la fermeture du bloc associé se fait sur une
 seule et même ligne :
 .Bd -literal -offset Ds
 if (foo) { bar(); return 0; }
 .Ed
 .Pp
 Ne pas utiliser d'accolades si la structure de contrôle n'est suivie
 d'aucune ou d'une seule directive écrite sur la même ligne :
 .Bd -literal -offset Ds
 while (foo());
 
 if (bar) return 0;
 .Ed
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .Sh LES MOTS CLÉS
 Ajouter un espace après chaque structure de contrôle
 .Ql if ,
 .Ql switch ,
 .Ql for
 et
 .Ql while
 pour les différencier des appels de fonctions.
 Ne pas ajouter d'espace après l'ouverture et avant la fermeture des
 parenthèses qui détourent leur(s) expression(s) :
 .Bd -literal -offset Ds
 if (i < 10) {
   foo(i);
 }
 .Ed
 .Pp
 Ajouter un espace après chaque point virgule qui sépare les expressions
 d'une boucle
 .Ql for
 sauf si l'expression qui suit est vide :
 .Bd -literal -offset Ds
 for (i=0; i<10; foo(i++));
 
 for (;;) { /* Boucle infinie */
   poll();
   if(bar) break;
 }
 .Ed
 .Pp
 Assimiler l'instruction
 .Ql sizeof
 à une fonction ; ne pas insérer d'espace entre le mot clé et son
 expression entourée de parenthèses :
 .Bd -literal -offset Ds
 sz = sizeof(int);
 .Ed
 .\""""""""""""""""""""""""""""""""""
 .Ss L'instruction Ql switch
 Limiter à quelques lignes le contenu de chaque
 .Ql case
 d'une instruction
 .Ql switch ,
 celle-ci devant donner à lire la seule répartition des traitements,
 fonction de la valeur que peut prendre l'expression du
 .Ql switch .
 Et non les traitements eux même, sauf s'ils sont triviaux.
 Un
 .Ql case
 au contenu trop fourni est alors le signe d'un manque de structure dans
 l'écriture du programme.
 .Pp
 Toujours ajouter une instruction
 .Ql default
 même si l'ensemble des valeurs que pourraient prendre l'expression du
 .Ql switch
 est censé être couvert par les différents
 .Ql case .
 C'est notamment le cas quand l'expression est une variable
 d'énumération.
 Utiliser alors la directive
 .Sy FATAL ,
 définie par la bibliothèque
 .Ql RSys
 .Pq en-tête In rsys/rsys.h ,
 pour signifier un comportement inattendu.
 Et ainsi pouvoir diagnostiquer une erreur dans la valeur de l'expression
 du
 .Ql switch ,
 ou un
 .Ql case
 manquant :
 .Bd -literal -offset Ds
 switch (i) {
   case FOO: foo(); break;
   case BAR: bar(); break;
   case QUX: qux = 1; break;
   default: FATAL("Unreachable code\en"); break;
 }
 .Ed
 .Pp
 Ajouter la directive
 .Sy FALLTHROUGH ,
 définie dans le fichier d'en-tête
 .In rsys/rsys.h
 de la bibliothèque
 .Ql RSys ,
 en fin des instructions
 .Ql case
 qui s'enchaînent.
 L'ajout de cette directive permet d'expliciter que c'est bien le
 comportement attendu et non l'oublie d'une instruction
 .Ql break ,
 en plus d'éviter un possible message d'avertissement à la compilation
 .Pq option Fl Wimplicit-fallthrough No de Xr gcc 1 Ns
  :
 .Bd -literal -offset Ds
 switch (c) {
   case 'a':
     foo = 1;
     FALLTHROUGH;
   case 'b':
     bar = 1;
     break;
   default:
     usage();
     break;
 }
 .Ed
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .Sh LE NOMMAGE
 .\""""""""""""""""""""""""""""""""""
 .Ss Les variables
 Nommer les variables en minuscules.
 Utiliser le tiret bas
 .Ql _
 au titre de séparateur entre les termes utilisés dans le nom des
 variables :
 .Bd -literal -offset Ds
 foo_bar
 .Ed
 .Pp
 Expliciter l'objet d'une variable dans son nom avec d'autant plus de
 précision que sa portée est grande.
 Une variable locale à un bloc de quelques lignes pourra se contenter
 d'un nom abrégé tel que
 .Va tmp
 pour un résultat temporaire, voire n'être qu'un seul caractère
 pour un indice
 .Va i
 ou un nombre d'éléments
 .Va n Ns
  ; leur contexte d'utilisation venant préciser ce que leur nom résume.
 Ce nom abrégé vient non seulement alléger l'écriture mais aussi en
 renforcer l'expressivité.
 Par exemple
 .Va tableau Ns Bq Va i
 reste plus clair que
 .Va tableau Ns Bq Va indice .
 .Pp
 Les variables globales sont au contraire à nommer de sorte à décrire ce
 qu'elles représentent, indépendamment de tout contexte d'utilisation,
 par construction distant de leur déclaration.
 Un compteur d'allocations global à un programme aura donc pour nom
 .Va compteur_allocations
 plutôt que
 .Va cpt_allocs .
 .Pp
 Pour une variable globale déclarée au niveau de l'interface d'une
 bibliothèque, préfixer ladite variable avec l'acronyme de la
 bibliothèque.
 Un compteur d'allocation global à la bibliothèque
 .Ql Foo ,
 et déclaré en tant que variable globale de son interface, sera alors
 nommé
 .Va foo_compteur_allocations .
 .\""""""""""""""""""""""""""""""""""
 .Ss Les fonctions
 Nommer les fonctions avec des caractères alphanumérique en minuscules,
 et séparer les termes qui composent leur nom par un tiret bas
 .Pq caractère Ql _ .
 .Pp
 Donner à une fonction un nom d'autant plus explicite que sa portée est
 importante.
 Une fonction utilitaire pourra se contenter d'un nom abrégé, tel que
 .Fn cmp
 pour une fonction de comparaison utilisée comme argument d'un appel à
 .Xr qsort 3
 au sein d'un fichier C.
 Là où une fonction partagée entre plusieurs unités de compilation aura
 un nom plus expressif, tel que
 .Fn compare_bar ,
 pour notamment expliciter le type
 .Vt struct bar
 des variables comparées.
 Jusqu'à préfixer le nom de la fonction par l'acronyme de la bibliothèque
 quand elle est une fonction d'interface de ladite bibliothèque.
 Pour la bibliothèque
 .Ql Foo ,
 une fonction d'interface sera alors nommée
 .Fn foo_compare_bar .
 .\""""""""""""""""""""""""""""""""""
 .Ss Les déclarations de types
 Utiliser des caractères alphanumériques en minuscules pour nommer les
 structures, unions et énumérations.
 Utiliser le tiret bas
 .Ql _
 pour séparer les différents termes qui composent leur nom.
 .Bd -literal -offset Ds
 struct foo {
   int bar;
   int baz
 };
 
 union foo_bar {
   double qux;
   int xyzzy;
 };
 .Ed
 .Pp
 Utiliser la même convention pour nommer les déclarations typedef.
 À l'exception du suffixe
 .Ql _T
 ajouté au nom de l'identificateur du type, en écho au suffixe
 .Ql _t
 souvent utilisé pour ce type de déclaration, mais réservé par le
 standard POSIX.
 .Bd -literal -offset Ds
 typedef int foo_T;
 typedef char foo_bar_T[256];
 .Ed
 .Pp
 Ne pas utiliser de déclaration typedef sur les structures, unions et
 énumérations de sorte à permettre leur déclaration anticipée.
 .Pp
 Préfixer le nom d'un type par l'acronyme de la bibliothèque dès lors
 qu'il est un type déclaré en tant que type de son interface.
 Par exemple, un type structuré de l'interface de la bibliothèque
 .Ql Foo
 sera nommé
 .Vt struct foo_mon_type .
 .\""""""""""""""""""""""""""""""""""
 .Ss Constantes et macros
 Utiliser des majuscules pour nommer les constantes symboliques, qu'elles
 soient des macros, des constantes énumérées, ou des variables déclarées
 comme constantes.
 Séparer par un tiret bas
 .Ql _
 les termes qui composent leur nom :
 .Bd -literal -offset Ds
 #define FOO_BAR 42
 
 enum foo {
   BAR_BAZ,
   QUX
 };
 
 static const enum foo FOO_XYZZY = BAR_BAZ;
 .Ed
 .Pp
 Nommer une constante ou une macro de manière d'autant plus explicite
 que sa portée est importante.
 Une constante définie localement à une fonction pourra se contenter
 d'un nom abrégé, jusqu'à n'être qu'un seul caractère, par exemple pour
 un nombre d'éléments constant
 .Sy N .
 Là où le nom d'une macro ou d'une constante définie dans un fichier
 d'en-tête se devra d'être plus explicite, tel que
 .Sy NOMBRE_ELEMENTS_MAX .
 Et être préfixée par l'acronyme de la bibliothèque si elle est déclarée
 comme macro ou constante de son interface.
 Par exemple, pour la bibliothèque
 .Ql Foo ,
 .Sy FOO_NOMBRE_ELEMENTS_MAX .
 .Pp
 Utiliser la convention typographique dite
 .Dq camel case
 pour nommer les arguments des macros ;
 les termes qui composent leur nom sont séparés par une variation de la
 casse typographique.
 Un terme débute par une majuscule, suivi de caractères
 alphanumériques en minuscule.
 .Bd -literal -offset Ds
 #define FOO_BAR(FooBar, Qux) ((FooBar) + (Qux))
 .Ed
 .Pp
 Ainsi, les arguments de macros sont différenciés des constantes
 symboliques et des variables.
 .Pp
 À noter que la macro elle même est nommée selon la même convention que
 celle utilisée pour les constante symboliques
 .Pq en majuscule et un tiret bas pour séparer ses différents termes .
 La parenthèse ouvrante, collée au nom de la macro, permettant de
 différencier les 2 cas.
 .\""""""""""""""""""""""""""""""""""
 .Ss Les variables et macros internes
 Suffixer par deux tirets bas
 .Ql __
 les variables membres d'une structure définie publiquement, qui n'ont
 cependant une signification qu'en interne des fonctions d'interface de
 la structure.
 L'enjeu étant de souligner que ces variables ne sont accessibles que par
 effet de bord, et ne s'addressent
 .Em pas
 aux utilisatrices et utilisateurs, qui ne devraient donc pas y accéder
 directement :
 .Bd -literal -offset Ds
 struct foo {
   double bar;
   int baz;
   int* qux__; /* Variable interne */
 };
 .Ed
 .Pp
 Utiliser le même suffixe en double tirets bas
 .Ql __
 pour nommer les variables internes à une macro, afin d'éviter de masquer
 les variables définies dans le contexte où la macro est développée :
 .Bd -literal -offset Ds
 #define FOO(Bar, N) { \e
   int i__; \e
   for (i__ = 0; i__ < N; Bar(i__), ++i__); \e
 } (void)0
 .Ed
 .Pp
 Suffixer les macros d'un fichier d'en-tête par deux tirets bas
 .Ql __
 dès lors qu'elles sont propres au fichier d'en-tête, et donc
 vraisemblablement inacessibles au delà :
 .Bd -literal -offset Ds
 #define FOO__(Type, Dim) \e
   struct Type {
     int i[Dim];
     float f[Dim];
   }
 FOO__(bar, 2)
 FOO__(baz, 3);
 FOO__(qux, 4);
 #undef FOO__
 .Ed
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .Sh LES FONCTIONS
 S'attacher à ce que chaque fonction reste simple et concise, en ne
 s'appliquant à ne lui faire faire qu'une seule chose.
 Ce faisant, le corps d'une fonction devrait être lisible sur un ou deux
 écran, avec comme référence la taille des terminaux telle que
 démocratisée à la fin des années 1970, à savoir 24 lignes.
 .Pp
 Un indice quant à la taille qu'une fonction devrait s'efforcer à avoir
 est donné par ses niveaux d'indentation.
 Plus elle compte de niveaux et plus elle devrait être ramassée.
 De même, un nombre de variables locales supérieur à dix peut être le
 signe d'une fonction trop dense.
 .Pp
 Écrire les directives qui contrôlent la portée d'une fonction et son
 type de retour sur une ligne séparée de son nom.
 L'expression régulière
 .Ql ^nom_de_fonction
 peut ainsi être utilisée pour la recherche d'une fonction dans les
 différents fichiers sources.
 .Pp
 Pour une déclaration, revenir à la ligne avant d'ouvrir la parenthèse de
 la fonction, précédée d'une indentation par rapport au nom de la
 fonction sur la ligne qui précède.
 Puis, lister les arguments de la fonction, en revenant à la ligne après
 chacun d'eux et en les alignant les uns par rapport aux autres.
 Ajouter la parenthèse fermante
 .Ql \&)
 et le point virgule
 .Ql \&;
 sur la ligne du dernier argument, sans espace supplémentaire :
 .Bd -literal -offset Ds
 extern LOCAL_SYM void
 foo_bar
   (struct foo* foo,
    const int qux,
    const float xyzzy);
 .Ed
 .Pp
 Les différentes parties qui composent le profil de la fonction sont
 ainsi identifiables par la seule mise en page de sa déclaration.
 .Pp
 Lors de sa définition, lister les arguments de la fonction sur la même
 ligne que le nom de la fonction, sans ajouter d'espace entre le nom de
 la fonction et sa parenthèse ouvrante.
 Si la liste des arguments dépasse la longueur maximale d'une ligne
 .Pq section Sx LA LONGUEUR DES LIGNES
 lister les arguments comme pour une déclaration :
 .Bd -literal -offset Ds
 void
 foo_bar(struct foo* foo, const int qux, const float xyzzy)
 {
   ...
 }
 .Ed
 .Pp
 Ordonner les arguments d'une fonction comme suit :
 .Bl -enum -compact
 .It
 pour une fonction d'interface, la variable sur laquelle la fonction
 opère ;
 .It
 les données d'entrées ;
 .It
 les données en sortie.
 .El
 .Pp
 Ajouter l'instruction
 .Ql const
 aux variables qui n'ont pas vocation à être modifiées par la fonction.
 Et ce quand bien même leur modification n'aurait aucune conséquence,
 comme pour les variables de données simples, copiées à l'appel de la
 fonction.
 L'objet étant de souligner quelles sont des variables en entrée :
 .Bd -literal -offset Ds
 static void
 foo
   (struct foo* foo,
    constr struct bar* bar,
    const int longueur,
    const int* liste,
    int* resultat);
 
 static INLINE double
 madd(const double a, const double b, const double c)
 {
   return a*b + c;
 }
 .Ed
 .Pp
 Ne passer en copie que les seuls paramètres en entrée de la fonction de
 type primitif
 .Pq Vt char , int , double , No énumération, ... .
 Utiliser un pointeur constant dès lors que le paramètre d'entrée est
 de type structuré, afin d'éviter le surcoût de sa copie à chaque appel de
 fonction ; son occupation mémoire étant a priori plus important
 qu'une donnée simple.
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .Sh LES VARIABLES
 Limiter le nombre de variables par bloc entre 5 et 10.
 Un nombre de variables trop important peut être le signe d'un manque de
 structure auquel un découpage en sous-fonction(s) pourrait remédier
 .Pq section Sx LES FONCTIONS .
 .Pp
 Initialiser les variables dès leur définition avec sinon une valeur
 valide, au moins une valeur par défaut.
 Et d'ainsi éviter l'utilisation de variables non initialisées.
 D'apparence peu critique pour les variables de type primitif, cette
 initialisation l'est bien plus pour les variables structurées, dont la
 liste des membres peut évoluer, sans que le code appelant n'est
 forcément à s'en soucier dès lors que ses membres sont correctement
 initialisés.
 Si elle existe, utiliser la constante proposée avec la structure pour
 initialiser une variable de ce type.
 .Pq voir section Sx LES CONSTANTES .
 En son absence n'initialiser que le premier membre de la variable ; le
 language C assure alors que les autres membres seront initialisés à 0.
 De même pour un tableau alloué sur la pile, initialiser son premier
 élément suffit à garantir que le reste du tableau sera initialisé à
 zero :
 .Bd -literal -offset Ds
 struct foo foo = FOO_DEFAULT;
 struct bar bar = {0};
 int qux[10] = {0};
 int i = 0;
 .Ed
 .Pp
 Au sein d'une même fonction, définir les variables au plus proche de
 leur utilisation de sorte à ce qu'un contexte resserré participe à les
 caractériser.
 Par exemple, une variable
 .Va i
 utilisée dans un bloc comme variable temporaire, et comme indice
 de boucle dans un autre gagnera en expressivité et en
 robustesse à être définie localement à chaque bloc ;
 les deux variables étant, par construction, non seulement séparées mais
 aussi sans effet de bord de l'une sur l'autre :
 .Bd -literal -offset Ds
 if(foo) {
   const int i = bar();
   if (i > max_i) max_val = i;
   if (i < min_i) min_val = i;
 } else {
   int i = 0;
   for(i = 0; i < N; ++i) qux(i);
 }
 .Ed
 .Pp
 Dans un même bloc, regrouper les définitions des variables dès lors
 qu'elles sont liés sémantiquements :
 .Bd -literal -offset Ds
 /* Tableau à traiter */
 double* liste = NULL;
 int longueur_liste = 0;
 .Ed
 .Pp
 Pour chaque groupe de variable, les définir par ordre décroissant de
 leur occupation mémoire a priori.
 Définir par exemple les variables structurées avant les variables de
 données simples.
 Cette convention s'inspire des contraintes des compilateurs C
 qui, pour garantir l'alignement des données eu égard à leur type,
 peuvent ajouter des octets de remplissage, augmentant ce faisant
 l'espace mémoire occupée par la fonction.
 Un sourcoût marginal qui néanmoins peut s'avérer significatif pour
 des fonctions appeler récursivement.
 Ordonner les variables par ordre décroissant de leur taille mémoire
 tend à limiter le nombre d'octets de remplissage nécessaire, et donc le
 coût mémoire associé.
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .Sh LES CONSTANTES
 Utiliser une énumération si les constantes à définir sont liées
 sémantiquement, et une macro sinon :
 .Bd -literal -offset Ds
 #define ID_INVALIDE ((unsigned)-1)
 
 enum { X, Y, Z };
 
 enum attribut {
   POSITION,
   NORMALE,
   TEXCOORD
 };
 .Ed
 .Pp
 Pour une énumération qui utilise des valeurs par défaut,
 ajouter si besoin une dernière constante qui définit le nombre de
 constantes valides ;
 sa valeur sera ainsi automatiquement mise à jour à chaque changement de
 l'énumération.
 Une telle constante est utile pour définir la cardinalité d'un tableau,
 comme valeur du dernier indice marquant la fin d'une itération,
 ou encore comme valeur vis à vis de laquelle la validité d'une variable
 du type énumérée peut être vérifiée.
 .Bd -literal -offset Ds
 enum molecule {
   H2O,
   CO2,
   O3,
   N2O,
   CO,
   CH4,
 
   NOMBRE_DE_MOLECULES
 };
 
 /* Vérifier qu'une constante définie une molecule valide */
 #define MOLECULE_EST_VALIDE(Mol) \e
   ((unsigned)(Mol) < NOMBRE_DE_MOLECULES)
 
 static const char* NOM_DES_MOLECULES[NOMBRE_DE_MOLECULES] = {
   "H2O", "CO2", "O3", "N2O", "CO", CH4
 };
 .Ed
 .Pp
 Définir les valeurs par défaut d'une structure à l'aide d'une variable
 constante du type concerné, déclarée en tant que variable statique.
 Et une macro qui liste ses valeurs par défaut, utilisé pour initialiser
 ladite variable :
 .Bd -literal -offset Ds
 struct foo {
   int bar;
   float baz;
 };
 #define FOO_DEFAULT__ {-1,0}
 static const struct foo FOO_DEFAULT = FOO_DEFAULT__;
 .Ed
 .Pp
 N'utiliser la macro que lorsqu'il est impossible d'utiliser la variable
 constante, en l'occurence pour initialiser, dès sa définition, les
 membres d'une variable structurée :
 .Bd -literal -offset Ds
 struct qux {
   struct foo foo;
   double
   int quux;
 };
 #define QUX_DEFAULT__ {FOO_DEFAULT__, 0}
 static const struct qux QUX_DEFAULT = QUX_DEFAULT__;
 .Ed
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .Sh LES STRUCTURES
 .Sh LES MACROS
 .Sh LES ALLOCATIONS DYNAMIQUES
 .Sh LA GESTION DES ERREURS
 .Sh LES PROGRAMME EN LIGNE DE COMMANDE
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .Sh FICHIERS
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .Sh VOIR AUSSI
 .Xr gcc 1 ,
 .Xr feature_test_macros 7
 .Pp
 .Rs
 .%A La Fondation pour le logiciel libre
 .%T Comment utiliser les licences GNU pour vos logiciels
 .%U https://www.gnu.org/licenses/gpl-howto.fr.html
 .Re