# 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) avec extension GNU (`-std=gnu99`)

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

    * **__attribute__((noreturn))**

    * **#pragma GCC message ""**

    * **#pragma GCC warning ""**

    * **#pragma GCC error ""**

TODO : `static` & `const`

---

{{>TOC}}

---

## Style 

DOIT 

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

    > Respecte un alignement strict des accolades ouvrantes et fermantes

* utiliser une indentation de **4** espaces

* contenir des ligne d'au plus **80** caractères

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

* contenir qu'une instruction par ligne

* contenir des espaces avant et après un opérateur sauf pour les opérateurs [unaires](https://fr.wikipedia.org/wiki/Op%C3%A9ration_unaire)

* avoir la constante placée à la gauche de l’opérateur d’équivalence (`==`)

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

Ne DOIT PAS

* utilisé l’opérateur ternaire `?:`

## Identifiants

DOIT

* contenir au maximum **31** caractères (a..z, 1..9, _) et en commençant par une lettre ([Snake Case](https://fr.wikipedia.org/wiki/Snake_case))

* être en **anglais américain**

* utiliser des traits de soulignement (_) pour séparer les mots

* laisser une ligne vide entre les fonctions

* Déclaration

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

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

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

        * `deprecated` 

        * `unavailable`

## Commentaires

* De style C (/*... */), sur une ou plusieurs lignes

* En minuscules et commence par une majuscule

* Phrase complète en français

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

### Doxygen

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

* *Note* : where you want the reader to "take notice" of the matter described in the section.

* *Attention* : can be used to highlight a particularly important note, one that you don't want the reader to overlook.

* *Warning* : should be used instead of Attention when there may be negative consequences to consider 

* *Remark* : can be used for notes that have lesser importance.

## Macros et préprocesseur

Directives du préprocesseur gcc.

DOIVENT

1. comporter un nom d'au maximum **31** caractères (A..Z, 0..9, _)

1. générer un message lors de la compilation avec `#pragma GCC poison` si obsolète

    > 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 utilisées pour afficher des avertissements ou des erreurs lors de la compilation.

    * Note : `#pragma message`

    * Warning : `#pragma GCC warning`

    * Error : `#pragma GCC error` 

    > N’est pas documenté dans Doxygen.

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

## É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 menu_select()

*/

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 :

        * read, write : Lis ou écris

        * 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 ayant 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]]