Objets et macros¶

Règles¶

1. Comportent au maximum 31 caractères :
   1. Lettres minuscules

      Les macros sont en lettres majuscules

   2. Nombres
   3. Trait de soulignement
2. Si plusieurs mots sont utilisés, ils sont séparées par des traits de soulignement
3. Les objets ne devant plus être utilisés, DOIVENT générer un message lors de la compilation (-Wall) si un appel est effectué.
   1. Les attributsdeprecated ou unavailable DOIVENT être ajoutés à la déclaration.
   2. 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));

/**
* @brief MACRO1
* @deprecated Utiliser NEWMACRO à la place
* @since Version x.x.xx
*/
#define MACRO1 43
#pragma GCC poison MACRO1

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