Normes de programmation en langage C++

Normes de programmation en langage C++ Bakhtouchi Abdelghani EMP, Bordj El Bahri bakhtouchi@yahoo.fr ANNEE: 2009/2010

Sommaire 1. Introduction.. 1 2. Présentation.. 1 2.1. Format des fichiers source. 1 2.2. Mise en forme du code source. 1 2.3. Longueur des lignes. 2 3. Les commentaires.. 2 3.1. Commentaires de fin de ligne.. 2 3.2. Commentaires en bloc. 3 4. Les déclarations.. 3 4.1. Les constantes. 3 4.2. Les variables 4 4.3. Les types de données.. 5 5. Espacement du code. 5 5.1. Lignes vides. 5 5.2. Espaces vides.. 6 5.3. L'imbrication.. 6 6. Les fonctions 7 7. Pratiques de programmation. 7 7.1. Affectation 7 7.2. Parenthèses.. 8 7.3. Les instructions break et continue.. 8 7.4. Opérateur égalité en virgule flottante 8 8. Programmation des TP 9 8.1. Structure générale d un projet. 9 8.2. Exemple complet 12 Références. 15

1. Introduction Les normes de programmation sont un ensemble de règles régissant la rédaction du code des programmes. Contrairement à ce que plusieurs élèves pensent, ces règles ne sont pas là pour embêter les programmeurs mais, au contraire, pour faciliter leur travail en améliorant la lisibilité et la clarté du code. Elles permettent, lorsqu elles sont bien appliquées, de se retrouver facilement dans le code écrit par d autres et même dans celui qu on a écrit soimême. Vous devez donc appliquer ces règles en tout temps. Obligez-vous à le faire et vous verrez que, très rapidement, cela deviendra un réflexe. Le présent document propose de manière synthétique des lignes directrices de mise en forme du code source du langage C++. Les normes portent plus spécialement sur les noms de fichier et leur organisation, les commentaires, les déclarations, les instructions, les expressions, l espace blanc, les conventions de nommage et les pratiques de programmation. Pourquoi des normes de programmation? 80% des coûts d un logiciel au cours de son cycle de vie vont à sa maintenance. Il est très rare qu un logiciel soit maintenu durant toute son existence par son auteur original. Les normes de programmation améliorent la lisibilité du code, ce qui permet à d autres informaticiens et programmeurs de le comprendre plus rapidement et plus à fond. De telles normes favorisent en outre : o l écriture de programmes corrects, o l obtention d un style consistant dans le code, o la détection des erreurs les plus courantes. Pour qu une norme fonctionne, chaque personne qui écrit du logiciel doit s y conformer. Tout le monde, enseignants comme élèves. 2. Présentation 2.1. Format des fichiers source Les fichiers doivent avoir les extensions suivantes : Fichier source :.cpp Fichier d en-tête :.h Le nom d un fichier doit être significatif (indiquant le contenu), la première lettre en majuscule. Le nom du fichier d'entête doit être identique au nom du fichier source dont il définit. Exemple: Vecteurs.h, Vecteurs.cpp. 2.2. Mise en forme du code source Un fichier source de plus de 2000 lignes est encombrant et devrait être évité. 1

Chaque fichier doit commencer par un en-tête identifiant les objectifs du fichier, son auteur ainsi que la date de création. Un fichier source peut contenir plusieurs sections logiques. Chaque section doit être séparée par une ligne vide et un commentaire identifiant chacune de ces sections. Suite à cet en-tête, le fichier source doit contenir les directives d importation "#include", puis, les déclarations de constantes, types et structures. Ne jamais spécifier de chemin d accès complet dans les directives "#include". C est dans l environnement de compilation qu on doit spécifier où aller chercher les fichiers d inclusion. (Ex: VC++ Touls>Options>Directories) #include NomLibrairie.h // Ok #include c:\dev\include\nomlibrairie.h // à éviter Utiliser la directive #include NomLibrairie.h pour des librairies définies par le développeur. Par conséquent, ces librairies doivent être placées dans le même répertoire. Utiliser la directive #include <NomLibrairie.h> pour des librairies standard fournies par le fabricant du compilateur. 2.3. Longueur des lignes Éviter les lignes de plus de 80 caractères pour s'assurer d'éditer et d'imprimer sans problème. Appliquer les règles suivantes pour une instruction sur plusieurs lignes : o Changer de ligne après une virgule ; o Changer de ligne avant un opérateur ; o Aligner la nouvelle ligne avec la ligne précédente ; nomlong1 = nomlong2 * (nomlong3 + nomlong4 nomlong5) + 4 * nomlong6; // Ok nomlong2 = nomlong2 * (nomlong3 + nomlong4 - nomlong5) + 4 * nomlong6; //à éviter 3. Les commentaires Inclure des commentaires bien pensés qui expliquent le programme. Le programme principal doit avoir une préface importante comprenant une brève description du problème, des références appropriées à des documents externes, le nom du programmeur ou de l'équipe de programmeurs, la date de la réalisation originale, et un journal des changements. Les sections de code difficiles, les formules complexes, les variables importantes doivent aussi être expliquées par des commentaires. Les programmes peuvent avoir deux styles de commentaires : 3.1. Commentaires de fin de ligne Les caractères " //" indiquent un début de commentaire et ce, jusqu'à la fin de la ligne où ils se trouvent. 2

Exemple: void main() // ceci est un commentaire char a; // ceci est aussi un commentaire 3.2. Commentaire en bloc Pour mettre en commentaire plusieurs lignes, utiliser plusieurs lignes de commentaires délimités par deux lignes contenant des étoiles. Exemple: * // ceci est un bloc // servant de commentaire * Les commentaires en bloc sont utilisés dans l'entête du fichier, les définitions des fonctions et pour expliquer des parties complexes du code. Exemple: // Nom du fichier // Information sur la version // Date // Auteur(e)(s) // Copyright (s il y a lieu) Seulement pour désactiver temporairement certaines parties du code comportant plusieurs lignes, utiliser les caractères " /* */ ". Pour désactiver temporairement une ligne utiliser les caractères "//". Exemple: /*If (a > b) max = a; else Max = b; */ //(a > b)? max = a : max = b; 4. Les déclarations 4.1. Les constantes Les constantes sont déclarées pour éviter de mettre des nombres dans le code excepté 0 et 1. La mise à jour de ces nombres sera plus rapide et plus sûre. 3

const double TAXE = 0.125; prix = prixbrut + prixbrut * TAXE; au lieu de: prix = prixbrut + prixbrut * 0.125; Les constantes doivent être déclarées après les inclusions de librairies. Le nom de la constante est écrit entièrement en majuscule et les mots internes doivent être séparés par un souligné "_". const int VALIDE = 1; enum Couleur BLEU, BLANC, VERT; const double NIVEAU_CRITIQUE = 4.0; Les constantes doivent toujours être définies avec " utiliser "#define". const double PI = 3.1416; enum Couleur BLEU, BLANC, ROUGE; au lieu de: #define PI (3.1416) #define BLEU (0) #define BLANC (1) #define VERT (2) 4.2. Les variables Le nom d'une variable commence toujours par une lettre composé, les autres mots commenceront par une lettre majuscule. const" ou " enum"; ne jamais minuscule. Si le nom est Les déclarations des variables doivent être placées seulement au début d un bloc (un bloc est une partie de code délimitée par une paire d accolades "" et ""). Initialiser les variables là où elles sont déclarées. void main() double prix = 0.0; // début du bloc principal int tailletableau = 10; if (condition) double total = prix; Les noms de variables doivent être significatifs pour éviter les ambiguïtés. Ils ne doivent pas commencer par "_" ou "$" même si c est permis par le langage. int longueurnom = 20; // au lieu de longnm int nombreoccurrence = 0; // au lieu de nboc Le nom d une variable booléenne doit être formulé comme une proposition. 4

5 bool estvide = true; Ne pas initialiser plusieurs variables à une même valeur dans une seule instruction. fchar = gchar = c ; // à éviter Les variables utilisées comme compteurs de boucle doivent être des lettres i, j, k, l, m, et elles doivent être définies au moment de leur utilisation uniquement. Exemple : for (int i = 0; i < 10; i++) for (int j = 0; j < 20; j++) // Code à exécuter Déclarer une variable par ligne afin d'encourager les commentaires. int taille; // taille du tableau int compteur; // nombre d'occurrences au lieu de: int taille, compteur; Ne pas placer des types différents sur la même ligne : int taille; double x; // à éviter 4.3. Les types de données Le nom d'un type commence toujours par une lettre majuscule. Si le nom est composé, les autres mots commenceront aussi par une lettre majuscule. Exemple: struct Point2D double x; double y; ; typedef Point2D *TableauPoint; 5. Espacement du code 5.1. Lignes vides Les lignes vides améliorent la lisibilité en séparant des sections de code qui sont logiquement reliées. Utiliser une ligne vide : Entre des sections d un fichier source ; Entre des définitions de structures; Entre les fonctions; Entre les variables locales d une fonction et sa première instruction ;

Avant un commentaire en bloc; Entre les sections logiques à l intérieur d une fonction. 5.2. Espaces vides Utiliser des espaces vides dans les cas suivants : Entre un mot réservé et une parenthèse. Exemple: while (condition) Après les virgules dans une liste d arguments. Exemple: enum Couleur BLEU, BLANC, ROUGE; double Vec[4] = 18, 15, 33, 11; x = Puissance(2, (i + 1)); Entre les opérateurs binaires et leurs opérandes. Exemple: a += c + d; a = (a + b) / (c * d); Entre les expressions dans une boucle for. for (expr1; expr2; expr3) 5.3. L'imbrication L'imbrication sert à augmenter la lisibilité du code en clarifiant le début et la fin de chaque bloc d'instructions. Les accolades du bloc doivent être placées au même niveau. L'imbrication de début de bloc doit être placée à la ligne suivant l'accolade, et à avec un décalage à droite. Si vous utiliser un éditeur tel que l'éditeur de Visuel Studio, un retour à ligne crée automatiquement un décalage (tabulation) à droite de 04 espaces. Si vous utiliser un éditeur de texte simple tel que Notepad, utiliser 04 espaces pour chaque décalage au lieu d'utiliser la tabulation. Exemple if (n > 0) // les deux accolades au même niveau // un décalage à droite de 4 espaces X = 20; for (int i = 0; i < n; i++) 6

6. Les fonctions // deux décalages à droite x = x + i; Une fonction doit exécuter une tâche précise et son nom doit bien décrire cette dernière. Si on a du mal à choisir un nom décrivant la fonction, c est peut-être parce qu on essaye de définir une fonction qui effectue plus d une tâche. Le nom d'une fonction commence toujours par une lettre majuscule. Si le nom est composé, les autres mots commenceront aussi par une lettre majuscule. Les prototypes de fonctions d un fichier source doivent être déclaré dans le fichier d entête correspondant. Les fonctions ne retournant aucune valeur, doivent avoir le type "void" Un commentaire en bloc doit être placé avant la déclaration de chaque fonction, identifiant les objectifs de la fonction et contenant une description de sa sortie. Les paramètres d'entrés et de sorties de la fonction doivent être alignés un par ligne est décrit par des commentaires. Les paramètres d'entrées doivent être précédés par le mot réservé " leurs modifications non intentionnées. Exemple: // La fonction MaxTab sert à calculer la valeur // max d un tableau d entier. // Sortie : la valeur du maximum const" pour éviter int MaxTableau(int *Tab, // un pointeur sur le tableau int taille) // taille du tableau // corps de la fonction 7. Pratiques de programmation 7.1. Affectation Éviter d utiliser l opérateur d assignation à un endroit où il peut être confondu avec l opérateur d égalité. Exemple : c = d; if (c!= 0) au lieu de : 7

if ((c = d)!= 0) // à éviter Eviter des instructions comportant plus d une incrémentation tels que : c++ = d++; a = c++ + d++; 7.2. Parenthèses Utiliser les parenthèses dans des expressions impliquant des opérateurs mixtes pour éviter les problèmes de précédence des opérateurs. if ((a == b) && (c == d)) // Ok au lieu de : if (a == b && c == d) // à éviter Utiliser les parenthèses dans une expression comme la suivante : (x >= 0)? a = x : a = -x; 7.3. Les l'instruction break et continue L 'instruction break ne doit être utilisé que dans une structure ne doit avoir qu un seul point de sortie. Exemple : for (i = 0; i < 1000; i++) if (a[i] == b) break; // à éviter ce bloc peut être remplacé par le bloc while suivant : trouve = FALSE; i = 0; while ((i < 1000) &&!trouve) if (a[i] == b) trouve = TRUE; i++; N utiliser jamais l'instruction continue. switch. Une boucle 7.4. Opérateur égalité en virgule flottante Ne jamais comparer deux nombres en virgule flottante avec l opérateur d égalité " ==". Il peut y avoir une différence non significative entre les deux nombres due à leur représentation interne, de sorte que l opérateur ne retournera jamais TRUE. Remplacer : par : float a, b; // ou double a, b if (a == b) 8

if (abs(a - b) < TOLERANCE) De la même façon, float f = 0.1 + 0.1 + 0.1; if (f == 0.3) peut retourner FALSE. 8. Programmation des TP 8.1. Structure générale d un projet Un projet doit contenir un programme principal, un ensemble de modules contenant les fonctions et l'ensemble de fichiers entête correspondant à ces modules. Exemple: Fichiers du TP1 Fichiers Source Principal.cpp Vecteur.cpp Matrice.cpp Fichiers entête Vecteur.h Matrice.h 1. Structure d un programme principal La structure générale d un programme principal doit contenir: Un commentaire en bloc contenant les informations du programme; Les inclusions des librairies standard et définit par l'utilisateur; Les déclarations de structures de données et de types; Des fonctions, en nombre d'exercice du TP, portant les noms Exo1(), Exo2(), Un titre d'exercice en commentaire doit suivre l'appel et la déclaration de chaque fonction. Exemple : // Présentation du TP // Date de création // Auteur(e)(s) #include <iostream.h> #include "Vecteur.h" void Exo1(void); void Exo2(void); 9

//Déclarations des structures de données void main() Exo1(); // Titre de l'exercice 1 //Exo2(); //Titre de l'exercice 2 // void Exo1(void) // Titre de l'exercice 1 // Programme relatif à l'exercice 1 void Exo2(void) // Titre de l'exercice 2 // Programme relatif à l'exercice 2 2. Structure générale d un fichier source (module) Un fichier source regroupe un ensemble de fonctions nécessaires pour l'exécution du programme principal. Ce fichier doit contenir: Un commentaire en bloc contenant les informations du module; Les inclusions des librairies standard et définit par l'utilisateur; Exemple : // Présentation du fichier source // Date de création // Date de la dernière mise à jour // Auteur(e)(s) #include <iostream.h> // Présentation de la fonction 1 // Sorties : présentation des sorties TypeFonction1 NomFonction1(paramètre1, // description paramètre1 paramètre2, // description paramètre2 ) // description paramètre // Corps de la fonction 1 10

// Présentation de la fonction 2 // Sorties : présentation des sorties TypeFonction2 NomFonction2( paramètre1, // description paramètre1 paramètre2, // description paramètre2 ) // description paramètre // Corps de la fonction 2 3. Structure générale d un fichier d entête Un fichier entête regroupe les prototypes des fonctions d'un fichier source. Ce fichier doit contenir: Un commentaire en bloc contenant les informations du fichier; Les inclusions des librairies standard et définit par l'utilisateur; Les déclarations de structures de données et de types; Exemple : // Présentation du fichier entête // Date de création // Date de la dernière mise à jour // Auteur(e)(s) // coordonnées d'un point dans un plan typedef struct Point2D double x; double y; *TableauPoint; // Présentation de la fonction 1 // Sorties : présentation des sorties TypeFonction1 NomFonction1( paramètre1, // description paramètre1 paramètre2, // description paramètre2 ); // description paramètre // Présentation de la fonction 2 11

// Sorties : présentation des sorties TypeFonction2 NomFonction2( paramètre1, // description paramètre1 paramètre2, // description paramètre2 ); // description paramètre 8.2. Exemple complet 1. Enoncé du TP Exercice 1: Surface et périmètre d'un rectangle a) Ecrire une fonction double Surface(double Longueur, double Largeur) qui calcul la surface d un rectangle. b) Ecrire une fonction double Perimetre (double Longueur, double Largeur) qui calcul le périmètre d un rectangle. Exercice 2: Affichage et lecture d'un tableau a) Ecrire une fonction void AfficheVec1(const int k1, const int k2, double *Vec) qui permet l'affichage de la partie comprise entre les indices k1 et k2 d'un tableau Vec. b) Ecrire une fonction void RemplirVec1(const int a, const int b, const int k1, const int k2, double *Vec) qui permet de remplir la partie comprise entre les indices k1 et k2 d'un tableau Vec par des valeurs aléatoires comprises entre a et b. Le fichier principal.cpp 2. Solution du TP *************// // Exemple d'illustration d'un TP contenant deux exercices // // Date de création: 28/09/2009 // // Auteurs : Cne Bouznade & Cne Bakhtouchi // *************// #include <iostream.h> #include "Geometrie.h" #include "Vecteurs.h" void Exo1(void); void Exo2(void); void main () //Exo1(); //-- Surface et périmètre d'un rectangle --// Exo2(); //-- Affichage et lecture d'un tableau --// //---------------------------------------------------------// void Exo1(void) //-- Surface et périmètre d'un rectangle --// //--- a) calcul de la surface d'un rectangle ----// double Longueur = 10; double Largeur = 12.5; 12

cout << "a) La surface du rectangle est: " << Surface(Longueur, Largeur) << endl; //--- b) calcul du périmètre d'un rectangle ----// cout << "b) Le périmètre du rectangle est: " << Perimetre(Longueur, Largeur) << endl; //-----------------------------------------------------------// void Exo2(void) //-- Affichage et lecture d'un tableau --// //-- a) Affichage des élément d'un tableau --// int k1 = 0; int k2 = 3; double Vec[4] = 18, 15, 33, 11; cout << "a) Les éléments du tableau sont: "; AfficheVec1(k1, k2, Vec); cout << endl; //-- b) Remplissage des élément d'un tableau --// int a = 0; int b = 5; RemplirVec1(a, b, k1, k2, Vec); cout << "Les éléments du tableau sont: "; AfficheVec1(k1, k2, Vec); cout << endl; Le module geometrie.cpp **************// // Module contenant des fonctions de géométrie. // // calcul de la surface et du périmètre d'un rectangle, // // Date de création: 28/09/2009 // // Date de la dernière mise à jour: 29/09/2009 // // Auteurs : Cne Bouznad & Cne Bakhtouchi // **************// *// // Calcul de la surface d'un rectangle // // Sortie : la surface du rectangle // *// double Surface(const double Longueur, // la longueur du rectangle const double Largeur) // la largeur du rectangle return Longueur * Largeur; // // Calcul du périmètre d'un rectangle // // Sortie : le périmètre du rectangle // // double Perimetre (const double Longueur, // la longueur du rectangle const double Largeur) // la largeur du rectangle return (Longueur + Largeur) * 2; Le fichier geometrie.h ************// // fichier entête du module Geometri.cpp contenant des // 13

// fonctions de géométrie. calcul de la surface et // // du périmètre d'un rectangle, // // Date de création: 28/09/2009 // // Date de la dernière mise à jour: 29/09/2009 // // Auteurs : Cne Bouznad & Cne Bakhtouchi // ************// //**************************************// // Calcul de la surface d'un rectangle // // Sortie : la surface du rectangle // //**************************************// double Surface(const double Longueur, // la longueur du rectangle const double Largeur); // la largeur du rectangle //**************************************// // Calcule du périmètre d'un rectangle // // Sortie : le périmètre du rectangle // //**************************************// double Perimetre (const double Longueur, // la longueur du rectangle const double Largeur); // la largeur du rectangle Le module Vecteur.cpp ***************// // Module contenant des fonctions de traitement des tableaux.// // affichage et lecture d'un tableau, // // Date de création: 28/09/2009 // // Date de la dernière mise à jour: 29/09/2009 // // Auteurs : Cne Bouznad & Cne Bakhtouchi // ***************// #include <iostream.h> #include <stdlib.h> #include <math.h> *// // Affichage de la partie d'un tableu comprise // // entre deux indices k1 et k2 // // Sortie : aucune // *// void AfficheVec1( const int k1, // indice de début de l'affichage const int k2, // indice de fin de l'affichage const double *Vec) // le tableau à afficher if (k2 < k1) cout << "--AfficheVec1: paramètres non valide!--" << endl; exit (0); for (int i = k1; i <= k2; i++) cout << " " << Vec[i]; ******// // Remplissage de la partie d'un tableu comprise // // entre deux indices k1 et k2 par des valeurs // // aléatoires comprises entre a et b // // Sortie : le vecteur Vec remplit // ******// 14

void RemplirVec1( const double a, // borne inférieur de l'intervalle const double b, // borne supérieur de l'intervalle const int k1, // indice de début du remplissage const int k2, // indice de fin du remplissage double *Vec) // le tableau à remplir if (k2 < k1) cout << "--RemplirVec1: paramètres non valide!--" << endl; exit (0); for (int i = k1; i <= k2; i++) Vec[i] = a + (b - a) * rand()/rand_max; Le fichier Vecteur.h ************// // fichier entête du module Vecteurs.cpp contenant des // // fonctions de traitement des tableaux. Affichage et // // lecture d'un tableau, // // Date de création: 28/09/2009 // // Date de la dernière mise à jour: 29/09/2009 // // Auteurs : Cne Bouznad & Cne Bakhtouchi // ************// *// // Affichage de la partie d'un tableu comprise // // entre deux indices k1 et k2 // // Sortie : aucune // *// void AfficheVec1( const int k1, // indice de début de l'affichage const int k2, // indice de fin de l'affichage const double *Vec); // le tableau à afficher ******// // Remplissage de la partie d'un tableu comprise // // entre deux indices k1 et k2 par des valeurs // // aléatoires comprises entre a et b // // Sortie : le vecteur Vec remplit // ******// void RemplirVec1( const double a, // borne inférieur de l'intervalle const double b, // borne supérieur de l'intervalle const int k1, // indice de début du remplissage const int k2, // indice de fin du remplissage double *Vec); // le tableau à remplir Références [1] Apache. The Jakarta Site Coding Standards, http://jakarta.apache.org/turbine/common/code-standards.html [2] Fabrizio Gotti "Normes de programmation en C#" College de Bois-de-Boulogne, 2009 [3] François Lemieux "Norme de programmation pour pages HTML" Atelier de génie logiciel, Ecole Polytechnique de Montréal, 2005 [4] GNU. Gnu Coding Standards, http://www.gnu.org/prep/standards_toc.html 15

[5] Marc Frappier "Norme de documentation des programmes" Département d informatique, Faculté des sciences, Université de Sherbrooke, 2004 [6] Marc Truitt "Visual Basic.Net Programming Guidelines" Information Technology Services, Johnson County, Kansas, 2004 [7] Ph. Gabrini "Normes de programmation", Département d'informatique, UQAM, 2005 [8] Professeurs et chargés de cours / Département D informatique et de génie logiciel "Normes de programmation" Faculté des sciences et de génie / Université LAVAL, 2004 [9] Sun Microsystems "Java Code Conventions", 1997 [10] Sun Microsystems. Code Conventions for the JavaTM Programming Language, http://java.sun.com/docs/codeconv/html/codeconvtoc.doc.html [11] Yves Roy "Normes de programmation en C++-2002" Document conçu dans le cadre du cours IFT-19946 Programmation orientée objet, 2002 16