# Règles de codage C

Le langage C utilisé avec le compilateur GCC :

* Standard [C99](https://www.open-std.org/JTC1/SC22/WG14/www/docs/n1256.pdf) (`-std=c99`)

* Extensions GNU

    * **__attribute__((deprecated))** (`-Wdeprecated-declaration`)

    * **__attribute__((noreturn))**

    * **#pragma GCC message ""**

    * **#pragma GCC warning ""**

    * **#pragma GCC error ""**

TODO : `static` & `const`

---

{{>TOC}}

---

## Style 

1. DOIT être de style [Allman](https://fr.wikipedia.org/wiki/Style_d%27indentation#Style_Allman)

1. L’indentation DOIT être de **4** espaces

1. Une ligne ne DOIT PAS avoir plus de 80 caractères

    > La barre oblique inversée DOIT être utilisée dans les longues chaine de caractères (string)

1. Une instruction par ligne

1. Une espace avant et après un opérateur DOIT être utilisée sauf pour les opérateurs [unaires](https://fr.wikipedia.org/wiki/Op%C3%A9ration_unaire)

1. L’opérateur ternaire `?:` ne DOIT PAS être utilisé

1. La constante DOIT être placée à la gauche de l’opérateur d’équivalence (`==`)

    > Prévient les erreurs lors d'ajout dans les blocs d'une seule instruction

## Identifiants

1. (a...z, A..Z, 0..9, _)

1. Ne DOIT PAS contenir plus de **31** caractères 

1. En **anglais américain** :

    * Lettres

        * Fonctions, variables, énumérations, structures, définition de type : 

            * Minuscules

    * Commence par une lettre

    * Si plusieurs mots sont utilisés, ils DOIVENT être séparées par des traits de soulignement

1. Déclaration

    1. Un objet ayant une visibilité locale DOIT avoir le modificateur `static` 

    1. Un objet « obsolète », DOIT avoir l'un des attributs :

        > Génération de message lors de la compilation (`-Wall`)

        * `deprecated` 

        * `unavailable`

## Commentaires

1. Précède l’élément à documenté, avec la même indentation

1. En minuscules et commence par une majuscule

1. Phrase complète en français

1. Sur une ou plusieurs lignes

1. De style C (/*... */)

1. Doxygen DOIT aussi être utilisé

    1. Les « décorations » (gras, italique, etc.) sont faites avec la syntaxe Markdown

## Macros et préprocesseur

Directives du préprocesseur gcc.

(A..Z, 0..9, _)

1. Les macros ne devant plus être utilisées, DOIVENT générer un message lors de la compilation avec `#pragma GCC poison`

    > Dans ce cas, la documentation doit indiquer le substitut à utiliser

    > Pour la définition d’une valeur entière signée (int), un `enum` DOIT être utilisé.

1. Définition conditionnel : Utiliser une forme évitant les répétitions.

1. Macros `#warning` et `#error` : Utilisées pour afficher des avertissements ou des erreurs lors de la compilation.

    > N’est pas documenté dans Doxygen.

1. Un `#define` est utilisé pour remplacer une valeur au moment de la compilation

    > Pour la définition d'une valeur entière, un `enum` DOIT être utilisé.

## Énumérations

DOIT être utilisée pour définir une série de valeurs.

* Permet l’utilisation dans une boucle avec des valeurs prédéfinis

## Typedef

1. En minuscule

1. Suivie des caractères **_t**

## Structures

```c

/**

* @brief Structure d'un menu local

* @sa MenuSelect

*/

struct menu {

/** @brief Caractère utilisé pour l'item */

char choice;

/** @brief Description de l'item */

char *item;

};

```

## Fonctions

Les fonctions définies dans une librairie de bas niveau pour du matériel (« driver ») DEVRAIENT utiliser les noms définis dans la fiche technique.

1. Le nom DOIT être dans le format suivant : _module_**_**_action_**_**_attribut_

    1. *module* signifie

        * Le nom d'un objet ou de la librairie

    1. *action* signifie :

        * set, get, clear : Règle, obtient ou vide un registre

        * read, write : Lis ou écris dans un fichier

        * init : Fonction d’initialisation

        * is : Vérifie un état

        * setup : Fonction de configuration des ports (p. ex. : AVR)

    1. *attribut* signifie 

        > TODO

1. Le modificateur `static` DOIT être utilisé dans la déclaration d’une fonction avec une vue locale

1. DOIT contenir qu’un seul `return`

## Fichiers

Structure des répertoires et fichiers

> Format selon la commande `tree --charset ascii`

```

.

|-- AUTHORS : Fichier contenant les noms et courriels des auteurs

|-- bin : Répertoire contenant le fichier exécutable et les librairies compilées

|-- ChangeLog : Fichier des changements

|-- config.h : Fichier optionel contenant les macros communes au programme dans son ensemble (-imacros)

|-- COPYING : Fichier de licence (standard GNU)

|-- docs : Répertoire de la documentation (.pdf)

|-- include : Répertoire des fichiers d’en-tête (.h)

|-- INSTALL

|-- lib : Répertoire des libraires externes (liens symboliques)

|-- Makefile.in : Fichier d'informations spécifiques du projet pour le Makefile

|-- NEWS :

|-- obj : Répertoire contenant les objets (.o)

|-- README : Fichier d'informations du projet, en format markdown

`-- src : Répertoire des fichiers sources (.c)

```

1. Nom du fichier :

    * Un préfixe en anglais de **8** caractères maximum pouvant contenir :

        * Lettres minuscule

        * Chiffres

        * Trait de soulignement

    * DOIT contenir un des suffixe suivants : 

        * `.h` : entête

        * `.c` : sources

1. Contenus

    * Section Doxygen :

        1. `@file` : Le nom du fichier

        1. `@brief`: Une brève description

        1. `@version`: Le numéro de version

        1. `@date`: La date de dernière modification

        1. `@author`: Une liste des participant(e)s et leur courriel

        1. `@copyright`: La liste des années et participant(e)s

    * Les fichiers d’entête contiennent en plus

        1. Une définition macro pour éviter de ré-inclure le fichier (<https://fr.wikipedia.org/wiki/Include_guard>).

[[Atmel AVR]]