Wiki » Historique » Version 87
Patrice Nadeau, 2023-12-31 10:43
1 | 1 | Patrice Nadeau | # Règles de codage C |
---|---|---|---|
2 | |||
3 | 68 | Patrice Nadeau | Le langage C, version [C99] (https://www.open-std.org/JTC1/SC22/WG14/www/docs/n1256.pdf) utilisé avec le compilateur [GCC](https://gcc.gnu.org/). |
4 | 1 | Patrice Nadeau | |
5 | > `gcc` n'est pas entièrement compatible avec le standard C99 (<https://gcc.gnu.org/c99status.html>). |
||
6 | |||
7 | --- |
||
8 | 73 | Patrice Nadeau | |
9 | {{>toc}} |
||
10 | 1 | Patrice Nadeau | |
11 | ## Style |
||
12 | |||
13 | 6 | Patrice Nadeau | Le code DOIT : |
14 | 5 | Patrice Nadeau | * Être dans le style [K&R](https://fr.wikipedia.org/wiki/Style_d%27indentation#Style_K&R) avec la variante *one true brace style* (1TBS): |
15 | 1 | Patrice Nadeau | * L’indentation est de 4 espaces |
16 | * Le « backslash » est utilisé pour les lignes de plus de 80 caractères |
||
17 | * Une instruction par ligne |
||
18 | * Une espace avant et après un opérateur sauf pour les opérateurs « [unaires](https://fr.wikipedia.org/wiki/Op%C3%A9ration_unaire) » |
||
19 | 46 | Patrice Nadeau | * Les fonctions, variables, constantes et `#define` DOIVENT être en [anglais américain](https://fr.wikipedia.org/wiki/Anglais_am%C3%A9ricain) |
20 | 52 | Patrice Nadeau | * Les commentaires DOIVENT |
21 | * Être de style C (/* ... */) |
||
22 | 50 | Patrice Nadeau | * En minuscules et commencer par une majuscule |
23 | 52 | Patrice Nadeau | * En français |
24 | 50 | Patrice Nadeau | * Précéder l’élément à documenté |
25 | 53 | Patrice Nadeau | * La documentation est faite a l'aide de commentaires [Doxygen](https://www.doxygen.nl/) : |
26 | 47 | Patrice Nadeau | * Chaque objet (fonctions, variables, etc.) DOIT être commenté/documenté : |
27 | * Dans le format [Javadoc](https://www.doxygen.nl/manual/docblocks.html) (/** */) |
||
28 | 52 | Patrice Nadeau | * Les « décorations » (gras, italique, etc.) sont faites avec la syntaxe Markdown |
29 | 1 | Patrice Nadeau | |
30 | 46 | Patrice Nadeau | Justifications : |
31 | 1 | Patrice Nadeau | * [K&R](https://fr.wikipedia.org/wiki/Style_d%27indentation#Style_K&R) |
32 | * Prévient les erreurs lors d'ajout dans les boucles n'ayant qu'une instruction comme bloc |
||
33 | 46 | Patrice Nadeau | * Support ASCII 7-bits |
34 | * Correspondance avec la fiche technique (datasheet) |
||
35 | 1 | Patrice Nadeau | * [Loi sur la langue officielle et commune du Québec, le français](https://www.publicationsduquebec.gouv.qc.ca/fileadmin/Fichiers_client/lois_et_reglements/LoisAnnuelles/fr/2022/2022C14F.PDF) |
36 | |||
37 | Exemple : |
||
38 | ``` c |
||
39 | 47 | Patrice Nadeau | /** |
40 | * @brief Fonction principale |
||
41 | 52 | Patrice Nadeau | * @return Une valeur |
42 | 47 | Patrice Nadeau | * @remark Note non importante |
43 | * @note Note générale |
||
44 | * @attention Note importante |
||
45 | * @warning Note conséquence négative |
||
46 | */ |
||
47 | 1 | Patrice Nadeau | int fonction(void) { |
48 | int x; |
||
49 | if (var != 1) { |
||
50 | 14 | Patrice Nadeau | x = x + 1; |
51 | 1 | Patrice Nadeau | y++; |
52 | printf("This is a long\ |
||
53 | line that should be splitted"); |
||
54 | } else { |
||
55 | 16 | Patrice Nadeau | x--; |
56 | }; |
||
57 | 20 | Patrice Nadeau | return 0; |
58 | } |
||
59 | ``` |
||
60 | |||
61 | 86 | Patrice Nadeau | <div style="page-break-after: always;"></div> |
62 | |||
63 | 1 | Patrice Nadeau | ## Fichiers |
64 | Le nom des fichiers DOIT être composé de la manière suivante : |
||
65 | * En minuscule |
||
66 | 79 | Patrice Nadeau | * Un préfixe de 8 caractères maximum |
67 | * Un des suffixe (extensions) suivants : |
||
68 | * `.h` : entête |
||
69 | * `.c` : sources |
||
70 | * Contient une section Doxygen : |
||
71 | * `@file` |
||
72 | * `@brief` |
||
73 | * `@version` |
||
74 | * `@date` |
||
75 | * `@author` |
||
76 | * `@copyright` |
||
77 | 1 | Patrice Nadeau | * Les fichier d’entête contiennent en plus |
78 | * Une section Doxygen « mainpage » |
||
79 | 79 | Patrice Nadeau | * Une définition macro pour éviter de ré-inclure le fichier. |
80 | 1 | Patrice Nadeau | |
81 | Exemple : |
||
82 | ```c |
||
83 | #ifndef _test_h |
||
84 | #define _test_h |
||
85 | /** |
||
86 | * @file : test.h |
||
87 | * @brief Description |
||
88 | * @version 0.00.01 |
||
89 | * @date 2023-02-26 |
||
90 | * @author Patrice Nadeau <pnadeau@patricenadeau.com> |
||
91 | * @copyright 2023 Patrice Nadeau |
||
92 | */ |
||
93 | |||
94 | /** |
||
95 | * @mainpage lcd |
||
96 | 37 | Patrice Nadeau | * @brief ATMEL AVR 8-bit C librairie |
97 | 1 | Patrice Nadeau | * @author Patrice Nadeau <pnadeau@patricenadeau.com> |
98 | * @version 0.0.02 |
||
99 | * @date 2023-03-27 |
||
100 | 54 | Patrice Nadeau | * @pre AVR supportés (testés en gras) : |
101 | 1 | Patrice Nadeau | * - ATmega88 |
102 | * - ATmega168 |
||
103 | 15 | Patrice Nadeau | * - **ATmega328P** |
104 | 1 | Patrice Nadeau | * @copyright |
105 | 13 | Patrice Nadeau | * @include{doc} LICENSE.txt |
106 | 1 | Patrice Nadeau | */ |
107 | |||
108 | ... |
||
109 | |||
110 | #endif /*_usart.h*/ |
||
111 | ``` |
||
112 | |||
113 | 85 | Patrice Nadeau | --- |
114 | 82 | Patrice Nadeau | |
115 | 60 | Patrice Nadeau | ## Objets |
116 | 1 | Patrice Nadeau | |
117 | 31 | Patrice Nadeau | * Comporter au maximum **31** caractères |
118 | * Être séparées par des traits de soulignement si comporte plusieurs mots |
||
119 | * Exceptions : |
||
120 | * Fonction et variables DOIVENT |
||
121 | * Être en minuscule |
||
122 | * Macros, constantes et `#define` DOIVENT |
||
123 | * Être en majuscule |
||
124 | 1 | Patrice Nadeau | |
125 | Justification : |
||
126 | * Linux kernel coding style : <https://www.kernel.org/doc/html/v4.10/process/coding-style.html#naming> |
||
127 | * GNU Coding Standards <https://www.gnu.org/prep/standards/html_node/Writing-C.html#Writing-C> |
||
128 | * Embedded C Coding Standard : <https://barrgroup.com/embedded-systems/books/embedded-c-coding-standard> |
||
129 | |||
130 | 61 | Patrice Nadeau | ### Déclarations locales |
131 | 1 | Patrice Nadeau | |
132 | Une déclaration n’ayant qu’une visibilité locale DOIT : |
||
133 | * Être de classe `static` |
||
134 | |||
135 | Exemple: |
||
136 | ``` c |
||
137 | /** |
||
138 | 75 | Patrice Nadeau | * @brief Fonction locale |
139 | * @return Une valeur |
||
140 | */ |
||
141 | 7 | Patrice Nadeau | static int local_func(void) { |
142 | 1 | Patrice Nadeau | ... |
143 | return 0; |
||
144 | } |
||
145 | ``` |
||
146 | |||
147 | 62 | Patrice Nadeau | ### Constantes |
148 | 1 | Patrice Nadeau | |
149 | Utilisé au lieu d’une macro quand le type ou la visibilité de la variable doit être définis. |
||
150 | |||
151 | Exemple : |
||
152 | |||
153 | ``` c |
||
154 | /** |
||
155 | 38 | Patrice Nadeau | * @name Liste des constantes |
156 | 1 | Patrice Nadeau | * @brief |
157 | */ |
||
158 | /** @{ */ |
||
159 | 38 | Patrice Nadeau | /** @brief La chaîne d'initialisation du projet */ |
160 | 1 | Patrice Nadeau | static const char INIT_STR[6] = "POWER"; |
161 | 38 | Patrice Nadeau | /** @brief Constante globale de la librairie `random` */ |
162 | 1 | Patrice Nadeau | extern int RANDOM_MAX = 25; |
163 | /** @} */ |
||
164 | |||
165 | 38 | Patrice Nadeau | /** @brief Constante */ |
166 | 1 | Patrice Nadeau | const int ANSWER 42; |
167 | ``` |
||
168 | |||
169 | 63 | Patrice Nadeau | ### Énumérations |
170 | 1 | Patrice Nadeau | |
171 | DOIT être utilisée pour définir une série de valeurs. |
||
172 | |||
173 | Exemple : |
||
174 | ```c |
||
175 | /** |
||
176 | 76 | Patrice Nadeau | * @name Liste des valeurs STATUS |
177 | 1 | Patrice Nadeau | * @brief |
178 | * */ |
||
179 | enum STATUS { |
||
180 | 76 | Patrice Nadeau | /** @brief Le processus est OK */ |
181 | 1 | Patrice Nadeau | STATUS_OK = 0, |
182 | 76 | Patrice Nadeau | /** @brief Le processus est en cours d'initialisation */ |
183 | 1 | Patrice Nadeau | STATUS_INIT, |
184 | 76 | Patrice Nadeau | /** @brief Le processus est arrêté */ |
185 | 1 | Patrice Nadeau | STATUS_HALTED |
186 | }; |
||
187 | ``` |
||
188 | |||
189 | 64 | Patrice Nadeau | ### Typedef |
190 | 1 | Patrice Nadeau | |
191 | Format : |
||
192 | * En minuscule, suivie de **_t** |
||
193 | |||
194 | Exemple : |
||
195 | ``` c |
||
196 | 39 | Patrice Nadeau | /** Type de la structure dans la librairie `ds1305` */ |
197 | 1 | Patrice Nadeau | typedef struct { |
198 | 39 | Patrice Nadeau | /** @brief Dernier deux chiffres : ≥ 00, ≤ 99 */ |
199 | 1 | Patrice Nadeau | uint8_t year; |
200 | /** @brief 01 - 12 */ |
||
201 | uint8_t month; |
||
202 | /** @brief 01 - 31 */ |
||
203 | uint8_t date; |
||
204 | /** @brief 1 - 7 */ |
||
205 | uint8_t day; |
||
206 | /** @brief 00 - 23 */ |
||
207 | uint8_t hours; |
||
208 | /** @brief 00 - 59 */ |
||
209 | uint8_t minutes; |
||
210 | /** @brief 00 - 59 */ |
||
211 | uint8_t seconds; |
||
212 | } ds1305_time_t; |
||
213 | ``` |
||
214 | |||
215 | 65 | Patrice Nadeau | ### Variables |
216 | 1 | Patrice Nadeau | |
217 | Exemple : |
||
218 | ``` c |
||
219 | 40 | Patrice Nadeau | /** @brief Variable locale */ |
220 | 1 | Patrice Nadeau | static int ctr; |
221 | 40 | Patrice Nadeau | /** @brief Variable globale */ |
222 | int RANDOM_CTR; |
||
223 | 1 | Patrice Nadeau | ``` |
224 | |||
225 | 66 | Patrice Nadeau | ### Structures |
226 | 1 | Patrice Nadeau | |
227 | Format |
||
228 | * En minuscule, séparé par des «underscores» si nécessaire. |
||
229 | |||
230 | Exemple : |
||
231 | ``` c |
||
232 | /** |
||
233 | 76 | Patrice Nadeau | * @brief Structure d'un menu local |
234 | 1 | Patrice Nadeau | * @see MenuSelect |
235 | */ |
||
236 | struct menu { |
||
237 | 76 | Patrice Nadeau | /** @brief Caractère utilisé pour l'item */ |
238 | 8 | Patrice Nadeau | char choice; |
239 | 76 | Patrice Nadeau | /** @brief Description de l'item */ |
240 | 8 | Patrice Nadeau | char *item; |
241 | 1 | Patrice Nadeau | }; |
242 | ``` |
||
243 | |||
244 | 67 | Patrice Nadeau | ### Fonctions |
245 | 1 | Patrice Nadeau | |
246 | Le nom DOIT être dans le format suivant : *Action***_***Item***_***Attribut*, où *Action* signifie : |
||
247 | 29 | Patrice Nadeau | * **set**, **get**, **clear** : Règle, obtient ou vide un registre |
248 | 1 | Patrice Nadeau | * **read**, **write** : Lis ou écris dans un fichier |
249 | * **init** : Fonction d’initialisation |
||
250 | * **is** : Vérifie un état |
||
251 | 36 | Patrice Nadeau | * **setup** : Fonction de configuration des ports (AVR) |
252 | 1 | Patrice Nadeau | |
253 | Exceptions |
||
254 | 41 | Patrice Nadeau | * Les fonctions définies dans une librairie de bas niveau pour du matériel (« driver ») devraient utiliser le nom définis dans la fiche technique. |
255 | 1 | Patrice Nadeau | |
256 | Une fonction DEVRAIT retourner une valeur. |
||
257 | 28 | Patrice Nadeau | * Type entier (oui/non) : |
258 | 1 | Patrice Nadeau | * Succès : **0** |
259 | * Erreur : **1** |
||
260 | * Type booléen (Librairie `<stdbool.h>`) |
||
261 | * **true** |
||
262 | * **false** |
||
263 | * Pointeur : |
||
264 | * **NULL** : Erreur |
||
265 | * Autre valeur : adresse du pointeur |
||
266 | |||
267 | Justification : |
||
268 | * [AVR1000b](https://ww1.microchip.com/downloads/en/Appnotes/AVR1000b-Getting-Started-Writing-C-Code-for-AVR-DS90003262B.pdf) |
||
269 | |||
270 | Exemple : |
||
271 | |||
272 | ``` c |
||
273 | /** |
||
274 | 42 | Patrice Nadeau | * @brief Vérifie si une horloge est est initialisée |
275 | 76 | Patrice Nadeau | * @param[in] nb Timer number. @n Valeurs possibles : |
276 | 24 | Patrice Nadeau | * − @arg **TIMER_1** |
277 | * − @arg **TIMER_2** |
||
278 | 1 | Patrice Nadeau | * @return |
279 | * @retval true Horloge *nb* est initialisée |
||
280 | 42 | Patrice Nadeau | * @retval false Horloge *nb* n'est PAS initialisée |
281 | 1 | Patrice Nadeau | * @pre init_timer |
282 | **/ |
||
283 | static bool is_timer_set(uint8_t nb); |
||
284 | |||
285 | ``` |
||
286 | |||
287 | ## Items déconseillés et retirés |
||
288 | 59 | Patrice Nadeau | |
289 | 76 | Patrice Nadeau | Les fonctions et variables ne devant plus être utilisés, DOIVENT générer un message lors de la compilation (`-Wall`) si un appel est effectué. |
290 | 80 | Patrice Nadeau | * Les attributs`deprecated` ou `unavailable` DOIVENT être ajoutés à la déclaration. |
291 | 1 | Patrice Nadeau | * La documentation DOIT indiquer les substituts à utiliser. |
292 | 59 | Patrice Nadeau | |
293 | Exemple : |
||
294 | ``` c |
||
295 | /** |
||
296 | * @brief OldFunction |
||
297 | 76 | Patrice Nadeau | * @deprecated Utiliser NewFunction à la place |
298 | 59 | Patrice Nadeau | * @since Version x.x.xx |
299 | */ |
||
300 | 84 | Patrice Nadeau | int OldFunction(void) __attribute__((deprecated)); |
301 | 59 | Patrice Nadeau | |
302 | /** |
||
303 | * @brief OldFunction |
||
304 | 76 | Patrice Nadeau | * @deprecated Utiliser NewFunction à la place |
305 | 1 | Patrice Nadeau | * @since Version x.x.xx |
306 | 59 | Patrice Nadeau | */ |
307 | 84 | Patrice Nadeau | int OldFunction(void) __attribute__((unavailable)); |
308 | 59 | Patrice Nadeau | ``` |
309 | 11 | Patrice Nadeau | |
310 | ## Préprocesseur |
||
311 | 1 | Patrice Nadeau | Directives du préprocesseur gcc. |
312 | |||
313 | ### #include |
||
314 | |||
315 | 43 | Patrice Nadeau | Pour inclure d’autres fichier comme les fichiers entête. |
316 | 1 | Patrice Nadeau | |
317 | ### #ifdef / ifndef |
||
318 | |||
319 | 76 | Patrice Nadeau | Surtout utilisé pour des options de compilation sur différentes plateforme. |
320 | 1 | Patrice Nadeau | Utiliser une forme évitant les répétitions. |
321 | |||
322 | > N’est pas documenté dans Doxygen. |
||
323 | |||
324 | Exemple : |
||
325 | ```c |
||
326 | const char BLUE = |
||
327 | #if ENABLED(FEATURE_ONE) |
||
328 | '1' |
||
329 | #else |
||
330 | '0' |
||
331 | #endif |
||
332 | ; |
||
333 | ``` |
||
334 | |||
335 | ### Diagnostiques |
||
336 | |||
337 | 78 | Patrice Nadeau | Les macros `#warning` et `#error` sont utilisées pour afficher des avertissements ou des erreurs lors de la compilation. |
338 | 1 | Patrice Nadeau | |
339 | > Ne sont pas documentées dans Doxygen. |
||
340 | |||
341 | Exemple : |
||
342 | ``` c |
||
343 | #ifndef usart_AVR |
||
344 | #error "__FILE_NAME__ is not supported on this AVR !" |
||
345 | #endif |
||
346 | |||
347 | #ifndef __test__ |
||
348 | #warning "test is not defined !" |
||
349 | #endif |
||
350 | ``` |
||
351 | |||
352 | ### Définitions |
||
353 | |||
354 | Un `#define` est utilisé pour remplacer une valeur au moment de la compilation |
||
355 | > Pour la définition d'une valeur « integer », un `enum` DOIT être utilisé. |
||
356 | |||
357 | Exemple : |
||
358 | ``` c |
||
359 | /** |
||
360 | 76 | Patrice Nadeau | * @name Nom des registres |
361 | 1 | Patrice Nadeau | */ |
362 | /** @{ */ |
||
363 | /** @brief USART1 */ |
||
364 | #define USART1 REG1 |
||
365 | /** @brief USART2 */ |
||
366 | #define USART2 REG2 |
||
367 | /** @} */ |
||
368 | |||
369 | USART1 = 0x0F; |
||
370 | ``` |
||
371 | |||
372 | ## Atmel AVR |
||
373 | |||
374 | Particularités pour les microcontrôleurs 8 bits AVR d’Atmel. |
||
375 | |||
376 | [Atmel AVR4027: Tips and Tricks to Optimize Your C Code for 8-bit AVR Microcontrollers](https://ww1.microchip.com/downloads/en/AppNotes/doc8453.pdf) |
||
377 | |||
378 | ### Fichier d’en-têtes |
||
379 | |||
380 | 25 | Patrice Nadeau | Vérification du modèle de microcontrôleur |
381 | > Via l'option `-m` de [gcc](https://github.com/embecosm/avr-gcc/blob/avr-gcc-mainline/gcc/config/avr/avr-mcus.def) |
||
382 | |||
383 | 1 | Patrice Nadeau | ```c |
384 | 25 | Patrice Nadeau | #ifndef defined (__AVR_ATmega48__) || (__AVR_ATmega48P__) || \ |
385 | (__AVR_ATmega88P__) || defined (__AVR_ATmega88__) || \ |
||
386 | (__AVR_ATmega168__) || defined (__AVR_ATmega168P__) || \ |
||
387 | (__AVR_ATmega328__) || defined (__AVR_ATmega328P__) |
||
388 | #warning "Cette librairie n'as pas été testée sur cette famille de microcontrôleur." |
||
389 | #endif |
||
390 | 1 | Patrice Nadeau | ``` |
391 | |||
392 | ### Macros |
||
393 | 45 | Patrice Nadeau | |
394 | Définis dans le fichier `config.h` |
||
395 | |||
396 | Liste : |
||
397 | 1 | Patrice Nadeau | * `F_CPU` : La fréquence utilisée par l'horloge (interne ou externe) du microcontrôleur |
398 | |||
399 | > Les « fuses » doivent correspondent à la bonne source de l'horloge. |
||
400 | |||
401 | ### Types |
||
402 | |||
403 | De nouveau type d'entier sont fournis avec la librairie `<stdint.h>`. |
||
404 | |||
405 | L'utilisation de ces types DOIT être utilisé afin d'exprimer le nombre de bit d'un objet. |
||
406 | |||
407 | ### Progmem |
||
408 | 44 | Patrice Nadeau | |
409 | <https://www.avrfreaks.net/s/topic/a5C3l000000U5SFEA0/t034767> |
||
410 | |||
411 | 1 | Patrice Nadeau | Pour mettre des variables en lecture seule dans la section FLASH au lieu de SRAM avec `<avr/pgmspace.h>`. |
412 | > L’accès à ces variables est faite via les macros de la librairie. |
||
413 | |||
414 | Le nom de la variable DOIT être suivie de **_P** |
||
415 | |||
416 | Exemple : |
||
417 | ```c |
||
418 | #include <avr/pgmspace.h> |
||
419 | ... |
||
420 | /** @brief Variable en FLASH */ |
||
421 | const int Variable1_P PROGMEM = 42; |
||
422 | ``` |
||
423 | |||
424 | ### Fonction main |
||
425 | Un microcontrôleur AVR ne termine jamais la fonction `main`. |
||
426 | |||
427 | * Déclarer la fonction main avec l’attribut `noreturn` |
||
428 | * La boucle sans fin la plus optimisé est le `for (;;)` |
||
429 | |||
430 | Justification : [AVR035](https://ww1.microchip.com/downloads/en/AppNotes/doc1497.pdf) |
||
431 | |||
432 | Exemple : |
||
433 | ```c |
||
434 | 26 | Patrice Nadeau | #include <avr/io.h> |
435 | |||
436 | 1 | Patrice Nadeau | /** |
437 | * @brief Never ending loop |
||
438 | */ |
||
439 | 83 | Patrice Nadeau | void main(void) __attribute__((noreturn)); |
440 | 1 | Patrice Nadeau | |
441 | /* main function definition */ |
||
442 | 9 | Patrice Nadeau | void main(void) { |
443 | 1 | Patrice Nadeau | ... |
444 | /* never return */ |
||
445 | for (;;) { |
||
446 | }; |
||
447 | }; |
||
448 | ``` |
||
449 | |||
450 | 70 | Patrice Nadeau | ### Opérations « atomiques » |
451 | 69 | Patrice Nadeau | Opérations ne devant pas être interrompus, comme charger un registre de 16 bits avec un registre de 8 bits. |
452 | 1 | Patrice Nadeau | |
453 | La librairie `avr-libc` (util/atomic.h) fournit des macros permettant la gestion entre autre des interruptions. |
||
454 | |||
455 | Les instructions critiques sont insérées dans un `ATOMIC_BLOCK`. |
||
456 | |||
457 | Exemple : |
||
458 | ```c |
||
459 | 72 | Patrice Nadeau | #include <util/atomic.h> |
460 | 1 | Patrice Nadeau | ... |
461 | ATOMIC_BLOCK(ATOMIC_RESTORESTATE) { |
||
462 | ... |
||
463 | } |
||
464 | ... |
||
465 | ``` |