Objets et macros¶

Variables, fonctions et macros

• Comportent au maximum 31 caractères
• Si plusieurs mots sont utilisés, ils sont séparées par des traits de soulignement
• Exceptions :
  • Fonction et variables DOIVENT
    • Être en minuscule
  • Macros et constantes DOIVENT
    • Être en majuscule
• Les objets ne devant plus être utilisés, DOIVENT générer un message lors de la compilation (-Wall) si un appel est effectué.
  • Les attributsdeprecated ou unavailable DOIVENT être ajoutés à la déclaration.
  • La documentation DOIT indiquer les substituts à utiliser.

Justification :

• Linux kernel coding style : https://www.kernel.org/doc/html/v4.10/process/coding-style.html#naming
• GNU Coding Standards https://www.gnu.org/prep/standards/html_node/Writing-C.html#Writing-C
• Embedded C Coding Standard : https://barrgroup.com/embedded-systems/books/embedded-c-coding-standard

Exemple :

/**
 * @brief OldFunction
 * @deprecated Utiliser NewFunction à la place
 * @since Version x.x.xx
 */
int OldFunction(void) __attribute__((deprecated));

/**
 * @brief OldFunction
 * @deprecated Utiliser NewFunction à la place
 * @since Version x.x.xx
 */
int OldFunction(void) __attribute__((unavailable));

Déclarations locales¶

Une déclaration n’ayant qu’une visibilité locale DOIT :

• Être de classe static

Exemple:

/**
 * @brief Fonction locale
 * @return Une valeur
 */
static int local_func(void) {
    ...
    return 0;
}

Constantes¶

Utilisé au lieu d’une macro quand le type ou la visibilité de la variable doit être définis.

Exemple :

/** 
 * @name Liste des constantes
 * @brief
 */
/** @{ */
/** @brief La chaîne d'initialisation du projet */
static const char INIT_STR[6] = "POWER";
/** @brief Constante globale de la librairie `random` */
extern int RANDOM_MAX = 25;
/** @} */

/** @brief Constante */
const int ANSWER 42;

Énumérations¶

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

Exemple :

/**
 * @name Liste des valeurs STATUS
 * @brief 
 * */
enum STATUS {
	/** @brief Le processus est OK */
	STATUS_OK = 0,
	/** @brief Le processus est en cours d'initialisation */
	STATUS_INIT,
	/** @brief Le processus est arrêté */
	STATUS_HALTED
};

Typedef¶

Format :

• En minuscule, suivie de _t

Exemple :

/** Type de la structure dans la librairie `ds1305` */
typedef struct {
    /** @brief Dernier deux chiffres : ≥ 00, ≤ 99 */
    uint8_t year;
    /** @brief 01 - 12 */
    uint8_t month;
    /** @brief 01 - 31 */
    uint8_t date;
    /** @brief 1 - 7 */
    uint8_t day;
    /** @brief 00 - 23 */
    uint8_t hours;
    /** @brief 00 - 59 */
    uint8_t minutes;
    /** @brief 00 - 59 */
    uint8_t seconds;
} ds1305_time_t;

Variables¶

Exemple :

/** @brief Variable locale */
static int ctr;
/** @brief Variable globale */
int RANDOM_CTR;

Structures¶

Format

• En minuscule, séparé par des «underscores» si nécessaire.

Exemple :

/**
* @brief Structure d'un menu local
* @see MenuSelect
*/
struct menu {
    /** @brief Caractère utilisé pour l'item */
    char choice;
    /** @brief Description de l'item */
    char *item;
};

Fonctions¶

• Le nom DOIT être dans le format suivant : Item**Action**Attribut

  • 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 (AVR)
    • Exceptions
      • 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.

• Contient les champs Doxygen

  • @brief : Brève description de la fonction
  • @param[in,out] paramètre Description : Si nécessaire, sinon ne pas inclure le champ
  • @arg : Valeur prédéfinie d'un paramètre (#, * *), sinon ne pas inclure le champs
  • @return : Description de la valeur retournée, sinon le terme Sans objet
  • @retval : Si une valeur de retour est prédéfinie, une ligne pour chaque valeur, sinon ne pas inclure le champs
  • @pre : Chaque précondition, sur une ligne séparée, sinon le terme Sans objet
  • @post : Chaque postcondition, sur une ligne séparée, sinon le terme Sans objet
  • @sa : Si une référence a un autre objet doit être faite (#), sinon le terme Sans objet
  • Le bloc d'exemple, si nécessaire
    • @par Example
    • @code
    • ...
    • @endcode

Une fonction DEVRAIT retourner une valeur.

• Type entier (oui/non) :
  • Succès : 0
  • Erreur : 1
• Type booléen (Librairie <stdbool.h>)
  • true
  • false
• Pointeur :
  • NULL : Erreur
  • Autre valeur : adresse du pointeur

Justification :

• AVR1000b

Exemple :

/**
* @brief Vérifie si une horloge est initialisée
* @param[in] nb Le numéro du timer parmi 
* @arg #TIMER_1
* @arg #TIMER_2
* @return
* @retval true Horloge *nb* est initialisée
* @retval false Horloge *nb* n'est PAS initialisée
* @pre init_timer
* @post Sans objet
**/
static bool is_timer_set(uint8_t nb);