Version 5 - Historique - Identifiants - SOP4003-Règles de codage C - Patrice Nadeau

Identifiants » Historique » Version 5

Patrice Nadeau, 2024-01-27 14:24

-Patrice Nadeau
+# Objets et macros
 Patrice Nadeau
 ## Règles
-Patrice Nadeau
+. Comportent au maximum **31** caractères :
 . Lettres minuscules
-Patrice Nadeau
+        > Les macros sont en lettres majuscules
-Patrice Nadeau
+. Nombres
 . Trait de soulignement
 . Si plusieurs mots sont utilisés, ils sont séparées par des traits de soulignement
 . 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.
-Patrice Nadeau
+. La documentation DOIT indiquer les substituts à utiliser.
-Patrice Nadeau
+## Exemple
-Patrice Nadeau
+``` 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));
 Patrice Nadeau
 /**
 * @brief MACRO1
 * @deprecated Utiliser NEWMACRO à la place
-Patrice Nadeau
+* @since Version x.x.xx
 */
 #define MACRO1 43
 #pragma GCC poison MACRO1
 ```
 Patrice Nadeau
 ## 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>
 Patrice Nadeau
 ### 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);
 ```

Projet

Général

Profil

Identifiants » Historique » Version 5