Règles de codage C¶

Le langage C utilisé avec le compilateur GCC :

• Standard C99 avec extension GNU (-std=gnu99)
  • attribute((deprecated)) (-Wdeprecated-declaration)
  • attribute((noreturn))
  • #pragma GCC message ""
  • #pragma GCC warning ""
  • #pragma GCC error ""

TODO : static & const

• Contenu
• Règles de codage C
  • Style
  • Identifiants
  • Commentaires
    • Doxygen
  • Macros et préprocesseur
  • Énumérations
  • Typedef
  • Structures
  • Fonctions
  • Fichiers

Style¶

DOIT

• être de 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

  sinon la barre oblique inversée DOIT être utilisée

• contenir qu'une instruction par ligne
• contenir des espaces avant et après un opérateur sauf pour les opérateurs unaires
• 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

• avoir un maximum d'une ligne vide entre les blocs

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)
• être en anglais américain
• 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, _)
2. 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é.

3. Définition conditionnel : Utiliser une forme évitant les répétitions.
4. 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.

5. 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
2. Suivie des caractères _t

Structures¶

/**
* \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
   2. action signifie :
      • read, write : Lis ou écris
      • get, set : Lis ou écris (registre matériel)
      • init : Fonction d’initialisation
      • is : Vérifie un état
      • setup : Fonction de configuration des ports (p. ex. : AVR)
   3. attribut signifie

      TODO

2. Le modificateur static DOIT être utilisé dans la déclaration d’une fonction ayant une vue locale
3. 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
2. Contenus
   • Section Doxygen :
     1. @file : Le nom du fichier
     2. @brief: Une brève description
     3. @version: Le numéro de version
     4. @date: La date de dernière modification
     5. @author: Une liste des participant(e)s et leur courriel
     6. @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