Projet

Général

Profil

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 : &ge; 00, &le; 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
```