star-style

star-c.7.in (56318B)

---

 .\" 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 October 14, 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 restent
 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 du projet ;
 .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 explicitent 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 qui propose la fonctionnalité recherchée.
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .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 des macros 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,
 en majuscule, 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 la police de caractères utilisée.
 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 auteures et auteurs sont encouragés à configurer leur éditeur de
 texte 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
 Ajouter un espace après l'ouverture du commentaire
 .Ql /*
 et avant sa fermeture
 .Ql */ .
 .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.
 Ajouter un espace entre le caractère
 .Ql * ,
 qui marque la continuation du commentaire, et la suite du commentaire :
 .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])
 {
   ...
 }
 
 static int
 qux(const int xyzzy)
 {
   ...
 }
 .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
 .Pq section Sx LA LONGUEUR DES LIGNES .
 .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("Code inaténiable\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 en est une fonction d'interface.
 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éclarations 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 minuscules.
 .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 {                                            \e
     int i[Dim];                                            \e
     float f[Dim];                                          \e
   }
 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 :
 .Bd -literal -offset Ds
 void
 foo_bar(struct foo* foo, const int qux, const float xyzzy)
 {
   ...
 }
 .Ed
 .Pp
 Si la liste des arguments dépasse la longueur maximale d'une ligne
 .Pq section Sx LA LONGUEUR DES LIGNES
 les lister comme pour une déclaration.
 .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 qu'elles 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.
 .Pp
 Les paramètres d'une fonction peuvent ne pas être utilisés à l'intérieur
 de celle-ci.
 C'est notamment le cas si les paramètres ne sont utiles que pour
 répondre à un profil de fonction spécifique ou dans un contexte de
 compilation particulier, par exemple pour le débogage.
 Lister ces paramètres en en-tête de la fonction, après
 la définition des variables locales, en les préfixant d'une conversion
 explicite vers un type vide :
 .Bd -literal -offset Ds
 static void
 foo(int x, int y, int z)
 {
   int i = 0;
   (void)y, (void)z; /* Paramètres inutilisés */
 
   i = bar(x);
   if (i < 42) {
     printf("Foobar\en");
   }
 }
 .Ed
 .Pp
 Cette conversion explicite quels paramètres sont ignorés, en plus de
 désactiver les avertissements de compilation quant à la définition de
 paramètres non utilisés
 .Pq option Fl Wunused-parameter No de Xr gcc 1 .
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .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.
 L'objet étant d'é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 changer.
 Si elle existe, utiliser la constante proposée avec la définition du
 type structuré pour initialiser ses membres
 .Pq voir section Sx LES STRUCTURES .
 En son absence, n'initialiser que le premier membre de la variable ; le
 language C assure alors que les autres membres seront initialisés à
 zéro.
 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 que le contexte dans lequel elles sont
 utilisées 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 alors, 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
 Regrouper les définitions des variables dès lors qu'elles sont liées
 sémantiquements.
 Les trier ensuite par taille mémoire décroissante, et enfin par ordre
 alphabétique :
 .Bd -literal -offset Ds
 /* Bibliothèque Foo */
 struct foo_args foo_args = FOO_ARGS_DEFAULT;
 struct foo* foo = NULL;
 
 /* Tableau à traiter */
 double* liste = NULL;
 int capacite = 0;
 int longueur = 0;
 .Ed
 .Pp
 Trier la définition des variables par taille mémoire tend à limiter le
 nombre d'octets de remplissage que le compilateur C ajoute pour garantir
 l'alignement mémoire de chaque variable eu égard à leur type.
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .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 peut alors servir à 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é peut être vérifiée :
 .Bd -literal -offset Ds
 enum molecule {
   CH4,
   CO,
   CO2,
   H2O,
   N2O,
   O3,
 
   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] = {
   "CH4", "CO", "CO2", "H2O", "N2O", "O3"
 };
 .Ed
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .Sh LES STRUCTURES
 Définir les structures en en-tête de fichier
 .Pq section Sx LA STRUCTURE D'UN FICHIER SOURCE ,
 à l'exeption des structures locales à une fonction.
 .Pp
 Lister les variables membres d'une structure suivant la même convention
 que pour la définition des variables d'un bloc
 .Pq section Sx LES VARIABLES Ns
  :
 les regrouper d'abord par sémantique, puis les trier par occupation
 mémoire décroissante, et enfin par ordre alphabétique.
 .Pp
 Ne définir qu'une variable membre par ligne.
 .Pp
 Pour une structure dont aucune fonction ne permet d'en initialiser les
 membres, définir une constante qui fixe leur valeur par défaut.
 Suffixer cette constante par
 .Ql DEFAULT
 ou
 .Ql NULL
 fonction de si une variable structurée ainsi initialisée est une donnée
 valide ou non.
 Déclarer cette constante en tant que variable statique et l'initialiser par
 une macro de même nom, différenciée de la variable constante par un
 double tiret bas final
 .Ql __ Ns
  :
 .Bd -literal -offset Ds
 struct arg {
   char* fichier; /* NULL <=> entrée standard */
   int verbosite;
 };
 #define ARG_DEFAULT__ {NULL, 0}
 static const struct arg ARG_DEFAULT = ARG_DEFAULT__;
 
 struct chaine {
   char* mem;
   int longueur;
   int capacite;
 };
 #define CHAINE_NULL__ {NULL,0,0}
 static const struct chaine CHAINE_NULL = CHAINE_NULL__;
 .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 autre variable structurée :
 .Bd -literal -offset Ds
 struct qux {
   struct chaine foo;
   int bar;
 };
 #define QUX_DEFAULT__ {CHAINE_NULL__, 0}
 static const struct qux QUX_DEFAULT = QUX_DEFAULT__;
 .Ed
 .Pp
 Éviter d'utiliser une déclaration typedef des structures afin
 d'autoriser leur déclaration anticipée.
 Et l'utilisation de pointeur vers une donnée structurée sans avoir sa
 définition.
 Si un déclaration typedef est néanmoins souhaitée, nommer le type
 structuré en suivant la convention de nommage des déclarations typedef
 .Pq section Sx Les déclarations de types .
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .Sh LES MACROS
 Pour définir une séquence d'instructions,
 préférer l'utilisation de fonctions aux macros.
 Déclarer la fonction avec la directive
 .Sy INLINE
 si son coût d'appel est un enjeu
 .Pq section Sx Les symboles internes à une unité de compilation .
 .Pp
 Regrouper la séquence d'instructions d'une macro dans un bloc terminé
 par l'instruction
 .Ql (void)0 .
 Elle peut ainsi être utilisée comme unique expression d'une structure de
 contrôle, et force l'ajout d'un point virgule
 .Ql \&;
 .Pq ou d'une virgule Ql \&,
 après son utilisation, telle n'importe quelle autre instruction C.
 .Pp
 En C, il est plus courant d'encapsuler les instructions d'une macro
 dans une structure de contrôle
 .Ql do { ... } while (0)
 plutôt que dans un bloc terminé par la converstion de l'entier zéro vers
 un type vide
 .Ql (void)0 .
 Si les deux écritures répondent aux mêmes objectifs, cette dernière
 convention évite les avertissements émis par certains compilateurs quant
 à l'utilisation d'une expression conditionnelle constante dans
 .Ql while (0) .
 .Pp
 Ouvrir le bloc sur la même ligne que le nom de la macro, en ajoutant un
 espace avant l'acolade
 .Ql { .
 Indenter le contenu du bloc par rapport à la directive de définition de
 la macro.
 Justifer à droite les caractères anti-slash
 .Ql \e
 en fin de chaque ligne de sorte à faciliter la lecture de la séquence
 d'instructions développée par la macro :
 .Bd -literal -offset Ds
 #define FOO(X, Y) {                                        \e
   if ((X) == (Y)) printf("Bar \en");                        \e
   (Y) += 2;                                                \e
 } (void)0
 .Ed
 .Pp
 À noter que dans l'exemple qui précède, les caractères anti-slash
 .Ql \e
 sont alignés en suivant des contraintes d'édition propres à ce manuel.
 Dans un fichier source, positioner l'anti-slash en tant que dernier
 caractère de lignes qui occupent la longueur maximale autorisée
 .Pq section Sx LA LONGUEUR DES LIGNES .
 .Pp
 Pour une macro dont la portée est l'unité de compilation, ne pas changer
 le déroulé des instructions de son contexte d'appel, par exemple en
 intégrant une directive
 .Ql return .
 Son utilisation contredirait l'exécution séquentielle du code et ce
 faisant nuirait à sa lisibilité.
 Il n'est donc
 .Em pas
 recommandé de définir une macro comme suit :
 .Bd -literal -offset Ds
 #define FOO(X) {
   if (bar(X))
     return -1;
 } (void)0
 .Ed
 .Pp
 Ne pas présupposer l'existance de variables externes à la macro,
 exeption faite des variables globales.
 L'objet étant de ne pas lier son bon fonctionnement au contexte local
 dans lequel elle est développée.
 L'écriture qui suit est donc
 .Em découragée Ns
  :
 .Bd -literal -offset Ds
 #define BAR(X,Y) {
   z = (X) + (Y);
   if (xyzzy(z))
     z += 1;
 }
 .Ed
 .Pp
 Contrairement aux macros définies à l'échelle d'une unité de
 compilation, une macro locale peut non seulement changer le fil
 d'exécution du contexte d'appel, mais aussi utiliser des variables
 externes.
 Et ce précisément en raison de son caractère local, qui lie étroitement
 la macro à son seul contexte d'utilisation.
 .Bd -literal -offset Ds
 static int
 foo(const int x)
 {
   char s[10] = {0};
   int line = 0;
   int err = 0;
 
   #define CALL(Func) {                                    \e
     if((err=(Func)) != 0) {                               \e
       line = __LINE__;                                    \e
       goto error;                                         \e
     }                                                     \e
   } (void)0
 
   CALL(bar(x, s));
   CALL(quux(s));
 
   #undef CALL
 
 exit:
   return err;
 error:
   fprinf(stderr, "erreur %d ligne %d\en", err, line);
   goto exit;
 }
 .Ed
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .Sh LES ALLOCATIONS DYNAMIQUES
 Préférer l'interface d'allocation proposée par la
 bibliothèque
 .Ql RSys
 via son fichier d'en-tête
 .In rsys/mem_allocator.h .
 Elle enrichit la gestion de la mémoire dynamique proposée par la
 bibliothèque C standard, notamment en enregistrant la quantité de
 mémoire allouée.
 .Pp
 Utiliser dès lors les fonctions
 .Fn mem_alloc ,
 .Fn mem_calloc
 et
 .Fn mem_realloc
 pour allouer dynamiquement de la mémoire.
 Leur profil est celui des fonctions équivalentes proposées par la
 bibliothèque C, à savoir ces mêmes fonctions mais sans le prefixe
 .Ql mem_
 .Po
 voir
 .Xr alloc 3 ,
 .Xr calloc 3 ,
 et
 .Xr realloc 3
 .Pc .
 .Pp
 Privilégier la fonction
 .Fn mem_calloc
 à
 .Fn mem_alloc
 de sorte à initialiser la mémoire allouée à zéro, et d'éviter ainsi
 d'utiliser des données non initialisées.
 .Pp
 Ne pas convertir le pointeur retourné par les fonctions d'allocation.
 La conversion d'un pointeur vide vers n'importe quel autre type de
 pointeur est déjà assuré par le langage C.
 .Pp
 Définir la taille du bloc mémoire à allouer via le type pointé par la
 variable destination :
 .Bd -literal -offset Ds
 p = mem_calloc(42, sizeof(*p));
 .Ed
 .Pp
 L'alternative qui consiste à épeller le type pointé en argument de
 .Ql sizeof
 non seulement nuit à la lisibilité des sources, mais laisse en plus
 l'opportunité d'introduire un bogue dès lors que le type de pointeur
 est mis à jour mais pas le nom du type renseigné à
 .Ql sizeof .
 .Pp
 Utiliser la fonction
 .Fn mem_alloc_aligned
 pour allouer un bloc mémoire dont l'adresse doit être alignée sur un
 nombre d'octets spécifique.
 Utiliser la fonction
 .Xr memset 3 ,
 de la bibliothèque C standard, pour forcer la mise à zéro du bloc ainsi
 alloué sinon rempli d'octets
 aléatoires :
 .Bd -literal -offset Ds
 foo = mem_alloc_aligned(sizeof(*foo), 128/* Alignement */);
 memset(foo, 0, sizeof(*foo));
 .Ed
 .Pp
 Vérifier chaque allocation en testant que l'adresse retournée n'est pas
 .Ql NULL .
 Traiter ce cas comme une erreur et non un bogue
 .Pq section Sx CENTRALISER LA SORTIE D'UNE FONCTION Ns
  :
 .Bd -literal -offset Ds
   foo = mem_calloc(1, sizeof(*foo);
   if (!foo) {
     res = RES_MEM_ERR;
     goto error;
   }
 .Ed
 .Pp
 Libérer la mémoire allouée via
 .Ql RSys
 avec la fonction
 .Fn  mem_rm
 dont le profil est le même que celui de la fonction
 .Xr free 3 Ns
  :
 .Bd -literal -offset Ds
 mem_rm(foo);
 .Ed
 .Pp
 Détecter la présence de fuites mémoires via la fonction
 .Fn mem_allocated_size
 qui retourne la quantité de mémoire qui reste allouée par la
 bibliothèque :
 .Bd -literal -offset Ds
 int
 main(void)
 {
   size_t sz = 0;
   int err = 0;
 
   ...
 
   if ((sz = mem_alloc_aligned()) != 0) {
     fprintf(stderr, "Fuites mémoires : %lu octets\en", sz);
     if (err == 0) err = 1;
   }
   return err;
 }
 .Ed
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .Ss Les allocateurs mémoire
 Dans son fichier d'en-tête
 .In rsys/mem_allocator.h ,
 la bibliothèque
 .Ql RSys
 définit en plus une interface d'allocateur mémoire.
 Au contraire de son interface d'allocation qui enregistre la mémoire
 allouée globalement par la bibliothèque,
 chaque allocateur enregistre ses seules allocations.
 .Pp
 Plusieurs types d'allocateurs sont proposés par la bibliothèque
 .Ql RSys ,
 chacun mettant en oeuvre une politique d'allocation qui lui est propre.
 Si bien qu'en fonction du contexte, un type d'allocateur particulier
 peut s'avérer plus approprié, par exemple pour réduire les coûts
 d'allocations/désallocations.
 Décrire les différents types d'allocateurs définis dans la bibliothèque
 .Ql RSys
 sort du cadre de cette documentation.
 Le lecteur est invité à se référer à son fichier d'en-tête
 .In rsys/mem_allocator.h
 pour plus d'informations.
 .Pp
 Les conventions listées précédemment quant aux allocations dynamiques
 s'appliquent à l'identique à l'utilisation des allocateurs.
 .Pp
 Utiliser un allocateur consiste à appeler des macros, dont le nom est
 une version en majuscule des fonctions de l'interface d'allocation.
 Avec en plus en premier argument l'addresse de l'allocateur concerné :
 .Bd -literal -offset Ds
 foo = MEM_CALLOC(&mem_default_allocator, 1, sizeof(*foo));
 
 \&...
 
 MEM_RM(&mem_default_allocator, foo);
 
 if (MEM_ALLOCATED_SIZE(&mem_default_allocator)) {
   fprintf(stderr, "Fuites mémoires\en");
 }
 .Ed
 .Pp
 avec
 .Va mem_default_allocator
 l'allocateur par défaut définit par la bibliothèque
 .Ql RSys .
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .Sh CENTRALISER LA SORTIE D'UNE FONCTION
 Utiliser la directive
 .Ql goto
 pour centraliser les traitements à effectuer en sortie de fonction, tels
 les affectations de variables de sorties, les libérations de variables
 locales temporaires, ou le renvoie d'une valeur en retour de la fonction.
 Regrouper ces traitements en fin de fonction sous le label
 .Ql exit
 dont la dernière instruction est la valeur retournée par la fonction.
 .Pp
 De même, centraliser la gestion des erreurs détectées pendant
 l'exécutation de la fonction sous un label
 .Ql error ,
 qui vise à revenir à l'état du programme avant l'appel de la fonction,
 et à préparer son retour compte tenu de l'erreur.
 Ses traitements recouvrent notamment la libération de
 l'espace mémorie alloué à destination de l'appelant, la restauration des
 données en mise à jour modifiées par la fonction avant la détection de
 l'erreur, ou la définition de valeurs à destination des variables en
 sortie en conséquence de l'erreur détectée.
 .Pp
 Placer le label
 .Ql error
 après le label
 .Ql exit .
 Terminer la gestion des erreurs par la directive
 .Ql goto exit ,
 de sorte à effectuer les traitements en sortie,
 .Em indépendants
 de la présence ou non d'une erreur d'exécution, et donc à appliquer en
 toute circonstance.
 En structurant les labels de la sorte, les traitements en sortie
 .Pq label Ql exit
 sont ainsi exécutés soit automatiquement au fil du bon déroulé de la
 fonction, sans que l'auteur(e) n'est nécessairement à le préciser.
 Soit après la détection d'une erreur dont la gestion explicite via la
 directive
 .Ql goto error
 précède la sortie de la fonction et ses traitements associés ; auxquels
 renvoit finalement la gestion des erreurs via la directive
 .Ql goto exit .
 .Bd -literal -offset Ds
 static res_T
 foo(const int bar, int** out_list)
 {
   int* list = NULL;
   res_T res = RES_OK;
 
   if (out == NULL) {
     res = RES_BAD_ARG;
     goto error;
   }
 
   if ((list = mem_calloc(42, sizeof(*list)) == NULL) {
     res = RES_MEM_ERR;
     goto error;
   }
 
   if ((res = quux(bar, list)) != RES_OK) goto error;
 
 exit:
   if (out_list != NULL) *out_list = list;
   return res;
 error:
   if (list) { mem_rm(list); list = NULL; }
   goto exit;
 }
 .Ed
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .Sh LES PROGRAMMES EN LIGNE DE COMMANDE
 Privilégier une interface en ligne de commande pour les programmes
 directement exécutables par l'utilisateur.
 À la fois simple et légère, elle s'intègre parfaitement aux shells, que
 ce soit en session interactive ou via des scripts.
 Avant d'être une interface utilisateur, elle est l'interface avec le
 système UNIX avec lequel le programme peut alors dialoguer, par exemple
 en terme de gestion des entrées/sorties ou de communication
 inter-processus.
 .Pp
 Analyser les arguments du programme en utilisant la fonction
 .Xr getopt 3
 définie par le standard POSIX.1-2001 dans l'en-tête
 .In unistd.h
 de la bibliohtèque C.
 Cette fonction assure la consistance de l'analyse des arguments et
 participe au respect des conventions énoncées par le standard POSIX pour
 les utilitaires en ligne de commandes.
 .Pp
 Proposer l'option
 .Fl h
 qui affiche le seul synopsis de la commande en guise de résumé de ses
 attendus et options.
 Réserver la description du programme et de ses options à sa page de
 manuel.
 Afficher ce même synopsis en cas d'erreur lors de l'analyse des
 arguments de sorte à renvoyer l'utilisateur vers la syntaxe de la
 commande.
 .Bd -literal -offset Ds
 static void
 usage(FILE* stream)
 {
   fprintf(stream, "usage: foo [-hv] [-b bar]\en");
 }
 
 int
 main(int argc, char** argv)
 {
   FILE* bar = NULL;
   int err = 0;
   int opt = 0;
   int verbosity = 0;
 
   while ((opt = getopt(argc, argv, "b:hv")) != -1) {
     switch (opt) {
       case 'a':
         if((bar = fopen(optarg, "r")) == NULL) err = 1;
         break;
       case 'h': usage(stdout); goto exit;
       case 'v': verbosity += (verbosity < 3); break;
       default: err = 1; break;
     }
     if (err) { usage(stderr); goto error; }
   }
   if (bar == NULL) bar = stdin;
 
   if ((err = foo(bar, verbosity)) != 0) goto error;
 
 exit:
   if(bar && bar != stdin) fclose(bar);
   return err;
 error:
   goto exit;
 }
 .Ed
 .Pp
 Si possible, permettre de lire les données en entrée du programme
 directement sur l'entrée standard.
 Il pourra ainsi être chaîné avec un autre processus en charge, par
 exemple, de pré-traiter ses données d'entrée.
 De même, écrire les données en sortie du programme sur la sortie
 standard pour qu'un autre utilitaire puisse en post-traiter le
 résultat.
 Si plusieurs fichiers d'entrée/de sortie sont lus/écrits par le
 programme, définir les données les plus à même d'être pré/post-traitées
 pour choisir lesquelles seront lues/écrites sur l'entrée/la sortie
 standard.
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .Sh FICHIERS
 .Bl -tag -width Ds
 .It Pa @APPPREFIX@/star-style/vimrc
 Fichier de configuration pour l'éditeur
 .Xr vim 1
 qui automatise la mise en page du code C suivant les conventions
 d'écriture définies dans ce manuel.
 Pour l'utiliser, lancer l'éditeur comme suit :
 .Bd -literal -offset Ds
 vim -u @APPPREFIX@/star-style/vimrc
 .Ed
 .El
 .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .Sh VOIR AUSSI
 .Xr gcc 1 ,
 .Xr vim 1 ,
 .Xr getopt 3 ,
 .Xr feature_test_macros 7
 .Pp
 .Rs
 .%A IEEE
 .%A The Open Group
 .%R Base Definitions, POSIX.1-2001
 .%T Section 12, Utility Conventions
 .Re
 .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