Wiki »

Identifiants » Historique » Révision 2

Révision 1 (Patrice Nadeau, 2024-01-20 21:21) → Révision 2/38 (Patrice Nadeau, 2024-01-27 13:55)

# Objets et macros 
 Variables, fonctions et macros 
 1. * Comportent au maximum **31** caractères : 
     1. Lettres minuscules 
     1. Nombres 
     1. Trait de soulignement 
 1. * Si plusieurs mots sont utilisés, ils sont séparées par des traits de soulignement 
 1. * 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é. 
     1. * Les attributs`deprecated` ou `unavailable` DOIVENT être ajoutés à la déclaration. 
     1. * 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 : &ge; 00, &le; 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); 
 ```