# 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 attributs`deprecated` 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 :

``` c

/**

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

``` c

/**

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

``` c

/** 

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

```c

/**

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

``` c

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

``` c

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

``` c

/**

* @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](https://ww1.microchip.com/downloads/en/Appnotes/AVR1000b-Getting-Started-Writing-C-Code-for-AVR-DS90003262B.pdf)

Exemple :

``` c

/**

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

```