commit fe872fb962c94a81756c07ba33fb719f78994cfc
parent 5fccf10ac0e96e168ef19622eb1e6e13b7867075
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Thu, 2 Jul 2026 12:46:05 +0200
Complète la section sur le nommage
Diffstat:
| M | doc/fr/star-c.7 | | | 112 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---------- |
1 file changed, 99 insertions(+), 13 deletions(-)
diff --git a/doc/fr/star-c.7 b/doc/fr/star-c.7
@@ -857,18 +857,26 @@ reste plus clair que
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 dynamiques global à un programme aura donc
-pour nom
+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 une nom d'autant plus explicite que sa portée est
+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
@@ -881,7 +889,7 @@ un nom plus expressif, tel que
pour notamment expliciter le type
.Vt struct bar
des variables comparées.
-Jusqu'à préfixer le nom de la fonction par le nom de la bibliothèque
+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 ,
@@ -911,7 +919,7 @@ Utiliser la même convention pour nommer les déclarations typedef.
.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
+souvent utilisé pour ce type de déclaration, mais réservé par le
standard POSIX.
.Bd -literal -offset Ds
typedef int foo_T;
@@ -920,13 +928,21 @@ typedef char foo_bar_T[256];
.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 ou des constantes énumérées.
+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 le nom des constantes.
+les termes qui composent leur nom :
.Bd -literal -offset Ds
#define FOO_BAR 42
@@ -934,20 +950,90 @@ enum foo {
BAR_BAZ,
QUX
};
+
+static const enum foo FOO_XYZZY = BAR_BAZ;
.Ed
.Pp
-Pour les arguments de macros, utiliser la convention typographique dite
+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
-en séparant les termes qui composent le nom de l'argument par une
-variation de la casse typographique.
-Chaque terme débute par une majuscule, suivi de caractères
-alphanumériques en minuscule :
+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, Qux) ((Bar) + (Bux))
+#define FOO_BAR(FooBar, Qux) ((FooBar) + (Bux))
.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
.Sh LES VARIABLES
