Norme de programmation pour le cours et les travaux pratiques

Transcription

1 Université du Québec École de technologie supérieure Service des enseignements généraux INF130 Ordinateurs et programmation Norme de programmation pour le cours et les travaux pratiques par François Cusson-Lafrenaye, ing. Objectif Ce document présente la norme de programmation qui est utilisée dans le cadre du cours INF130. Les notes de cours et les exemples donnés utilisent cette norme de programmation et les travaux pratiques remis par les étudiants doivent respecter cette norme de programmation. Nom des variables Le langage VBA impose les règles suivantes lorsque vient le temps de nommer une variable : Le premier caractère doit être une lettre ; La longueur maximum est de 255 caractères ; L'espace, le point, et les caractères &, $ et # ne sont pas permis, mais le caractère _ (souligné) peut être utilisé ; Le nom doit être unique à l'intérieur de sa portée ; À ces règles, nous ajoutons les normes suivantes pour INF130 : Le nom doit être significatif et explicite ; Toutes les lettres formant le nom doivent être minuscules ; Le caractère _ (souligné) doit être utilisé pour séparer les mots ; Les caractères accentués (é, à, ê, ç, etc.) peuvent être utilisés ou non ; Des abréviations peuvent être utilisées, mais elles doivent êtres explicites. age prénom montant_total nombre_lignes_vides nb_lignes_vides a pnom montanttotal NombreLignesVides nbr_lg_vds INF130 Ordinateurs et programmation Norme de programmation page 1 de 7

2 Nom des constantes VBA impose les mêmes règles au nom de chacune des constantes ainsi qu au nom de chacune des variables. La norme de programmation d INF130 ajoute les règles suivantes : Le nom doit être significatif et explicite ; Toutes les lettres formant le nom doivent être MAJUSCULES ; Le caractère _ (souligné) doit être utilisé pour séparer les mots ; Les caractères accentués (É, À, Ê, Ç, etc.) peuvent être utilisés ou non ; Des abréviations peuvent être utilisées, mais elles doivent êtres explicites. PI TPS POURCENTAGE_POURBOIRE ADRESSE_DEPART_CELLULE ADR_DEPART_CELL P tps PourcentagePourboire ADRESSEDEPARTCELLULE ADR_DPT_CL Nom des programmes et des sous-programmes VBA impose les mêmes règles au nom des programmes et des sous-programmes qu au nom des variables et des constantes. Pour bien distinguer les noms de programmes et de sous-programmes des noms des variables et des constantes, nous ajoutons les règles suivantes en INF130 : Le nom doit illustrer l utilité d une procédure ou la valeur de retour d une fonction ; La première lettre de chaque mot formant le nom doit être MAJUSCULE et toutes les autres lettres, minuscules ; Le caractère _ (souligné) doit être utilisé pour séparer les mots ; Les caractères accentués (é, à, ê, ç, etc.) peuvent être utilisés ou non ; Des abréviations peuvent être utilisées, mais elles doivent êtres explicites. Afficher_Infos Calculer_Coordonnées Est_Impair Est_Une_Lettre Sinus Afficher Calculer afficherinfos CalculerCoordonnées Fonction_2 INF130 Ordinateurs et programmation Norme de programmation page 2 de 7

3 Nom des modules VBA impose les mêmes règles au nom des modules qu à tous les autres noms vus précédemment. En INF130, le nom des modules suit les mêmes normes que le nom des programmes et des sousprogrammes avec cette simple règle en plus : Le nom doit être préfixé par «Module_». Module_Tests Module_Mathématiques Module_Maths Module_Simulation Module_Analyse_Structures Tests maths Mod_Maths Module2 ModuleAnalStruct En-tête des modules Le code source de chaque module doit commencer par un commentaire d en-tête qui présente les éléments suivants : Le nom du module, préférablement en majuscules ; Une description générale du module ; Le nom du ou des auteurs du module ; La liste des procédures et des fonctions publiques avec une courte description pour chacune ; Optionnellement, les dates de révision du code source du module avec une description des modifications apportées. Les commandes Option Explicit et Option Base peuvent être insérées avant ou après l en-tête. Exemple : MODULE_BD_EMPLOYÉS Librairie de fonctions permettant la gestion des informations contenues dans la table Employés (base de données). Par Francois Cusson-Lafrenaye, ing. École de technologie supérieure (ÉTS) Fonctions publiques : Ajouter_Employé - Ajoute un employé à la liste Consulter_Employé - Retourne les informations sur un employé Modifier_Employé - Modifie les informations d'un employé Supprimer_Employé - Supprime un employé de la liste Procédures publiques : Aucune INF130 Ordinateurs et programmation Norme de programmation page 3 de 7

4 En-tête des programmes et des sous-programmes Chaque procédure et chaque fonction doit être précédée d un commentaire d en-tête offrant : Une ligne «séparatrice» d environ 80 caractères formée de tirets, d astérisques ou autres ; Le nom de la procédure ou de la fonction, préférablement en majuscules ; Une description du programme ou du sous-programme, permettant de comprendre rapidement son utilité sans avoir à lire ses lignes de code ; La liste des paramètres à recevoir avec, pour chacun, une courte description et le type de données à utiliser. Indiquez «Aucun» si aucun paramètre n est nécessaire ; Une description de la valeur de retour s il s agit d une fonction, avec son type de données. Exemple : * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * NOM_CARTE Cette fonction retourne le nom de la carte (Visa, MasterCard ou American Express) en fonction du numéro entré. Paramètres : numero - Le numéro de la carte (type: String) Valeur de retour : Retourne le nom de la carte ou une chaine vide si le nom est inconnu (type: String) Autres exemples pour la forme : '================================= '= NOM_DU_SOUS_PROGRAMME '= '= ' ' NOM_DU_SOUS_PROGRAMME ' ' 'o ooooo ooo ooooo ooo ooooo ooo ooooo 'o NOM_DU_SOUS_PROGRAMME 'o 'o ' ' NOM_DU_SOUS_PROGRAMME ' ' Indentation et aération du code source L indentation et l aération du code source sont essentielles pour que le code source soit lisible par un être humain normalement constitué. L indentation représente l espace laissé entre la marge de gauche et le début de la ligne de code VBA. L aération est la ligne vide laissée entre deux blocs de code. Un bloc de code regroupe les instructions d un même «niveau» et d une même «idée». Le corps d une procédure ou d une fonction est formé par un ou plusieurs blocs de code qui s exécutent les uns après les autres. INF130 Ordinateurs et programmation Norme de programmation page 4 de 7

5 Chaque bloc de code commence par un commentaire (voir plus loin) et est isolé des autres blocs de code par une ligne vide. Une seule ligne vide suffit pour séparer deux blocs de code. ' Déclaration des variables Dim borne_sup As Integer ' Contient la borne supérieure de l'intervalle Dim somme As Integer ' Contient la somme des nombres Dim nombre_courant As Integer ' Compteur de boucle ' Initialisation du nombre courant et de la somme nombre_courant = 1 somme = 0 ' Saisie de la borne au clavier borne_sup = Val(InputBox("Quelle est la borne supérieure?")) Chaque bloc de code est indenté par rapport à son «parent». L indentation est d une seule tabulation (touche TAB sur le clavier) correspondant à quatre (4) espaces. Voici quelques exemples de «parents» en-dessous desquels il faut indenter le code : Sub, Function, If, Else, ElseIf, Select Case, Case, Do, While, For, Type et With. Les branches du If et du Select Case sont indentées au même niveau que le If ou le Select Case. Public Sub Exemple_Indentation ' Déclaration des variables Dim borne_sup As Integer ' Contient la borne supérieure de l'intervalle Dim somme As Integer ' Contient la somme des nombres Dim nombre_courant As Integer ' Compteur de boucle ' Boucle : le contenu de la boucle est indenté par rapport au "Do" Do While nombre_courant < borne_sup Loop End Sub ' If : Chaque branche a son contenu indenté mais les Else et ElseIf ' sont au même niveau que le If If nombre_courant < 10 Then somme = somme + 1 ElseIf nombre_courant < 20 Then somme = somme + 2 Else Somme = somme + 3 End If INF130 Ordinateurs et programmation Norme de programmation page 5 de 7

6 Lorsqu une instruction doit être écrite sur plus d une ligne pour faciliter la lecture ou l impression du code source, la deuxième ligne et les suivantes doivent être indentées par rapport à la première ligne d une ou de plusieurs tabulations. Voici quelques bons exemples : Call MsgBox("Je ne crois pas à l astrologie parce que Pluton n est plus " _ & "une planète! De plus, des astrologues m ont prédit une mauvaise " _ & "vie et je n ai pas aimé ça...", vbexclamation, "Sceptique?") Public Function Calculer_Salaire(ByVal nombre_annees_experience As Integer, _ ByVal nombre_heures_travaillees As Single, ByVal date_embauche As Date, _ ByVal nombre_bonnes_decisions As Integer) As Single Public Function Calculer_Salaire(ByVal nombre_annees_experience As Integer, _ ByVal nombre_heures_travaillees As Single, _ ByVal date_embauche As Date, _ ByVal nombre_bonnes_decisions As Integer) _ As Single Commentaires dans le code source Les commentaires dans le code source sont essentiels pour comprendre le code source une fois qu il a été écrit, par soi-même ou par d autres. Ils sont aussi un excellent outil lors de la création du code source : en écrivant les commentaires avant le code, le programmeur s assure que la logique désirée sera bien codée lors de la traduction du français en langage VBA. Un bon commentaire doit être court, précis et il ne doit pas répéter le code VBA qu il décrit. Il doit être écrit dans un bon français et être autant que possible exempt d erreurs. Tout d abord, toutes les variables déclarées doivent être commentées, même celles qui semblent évidentes. Le commentaire est alors placé sur la même ligne que la déclaration et tous les commentaires sont alignés ensemble. Ensuite, tous les blocs de code doivent commencer par un commentaire indiquant, en français, ce que réalisent les quelques lignes qui suivent. Si une logique complexe est utilisée, elle est expliquée dans ce commentaire. Les boucles doivent être décrites au début de celles-ci et non à la fin, même si la condition de boucle est placée à la fin. Les commentaires de blocs de code doivent avoir la même indentation que le bloc de code commenté. Une bonne façon de savoir si les commentaires écrits sont bons est de ne lire que les commentaires d un programme : si on comprend rapidement comment le programme fonctionne sans avoir à lire le code VBA, c est bon! INF130 Ordinateurs et programmation Norme de programmation page 6 de 7

7 Mais attention, il est facile d écrire de mauvais commentaires qui ne font qu alourdir le code! Voici quelques mauvais exemples : Public Sub Exemples_Mauvais_Commentaires ' Dims (français?) Dim borne_sup As Integer ' La variable borne_sup est un Integer (...!) Dim somme As Integer ' La somme (quelle somme? somme de quoi?) ' Boucle (boucle pourquoi? jusqu à quand? comment?) Do While nombre_courant < borne_sup ' Si nombre_courant est plus petit que 10 (répétition du code VBA) If nombre_courant < 10 Then somme = somme + 1 ' Sinon (sinon quoi?) ElseIf nombre_courant < 20 Then somme = somme + 2 ' Sinon, on ne fait rien (ce n est pas vrai!) Else Somme = somme + 3 End If ' Fin de la boucle (commentaire inutile, on le sait par l indentation) Loop ' Fin de la procédure (commentaire inutile ici aussi) End Sub Consistance Enfin, le point le plus important à considérer lorsqu une norme de programmation est appliquée est la consistance : lorsqu une méthode est choisie (utilisation d accents ou non, style des en-têtes, inspiration pour les noms de variables et de sous-programmes, etc.), elle doit être utilisée partout, dans tous les modules du projet (classeur) programmé. INF130 Ordinateurs et programmation Norme de programmation page 7 de 7