# 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}}

---

## Identifiants

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

    > ANSI standards

    * a @ z

    * A @ Z

    * 0 @ 9

    * Trait de soulignement (__)

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

    * Lettres

        * Macros :

            * Majuscules et minuscules

                > La parie principale DOIT être en majuscule

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

            * Minuscules

    * Nombre

    * 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 :

        1. Un des attributs :

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

            * `deprecated` 

            * `unavailable`

        1. Les commentaires Doxygen : 

            * `@deprecated` : Indications sur le remplacement à utiliser

            * `@since` : Depuis quel version le changement est apparue

## 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)

```

## Fichiers sources

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>).

[[Style]]

## 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.

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 « integer », un *enum* DOIT être utilisé.

[[Énumérations]]

[[Typedef]]

[[Variables]]

[[Structures]]

[[Fonctions]]

[[Atmel AVR]]