Conventions de codage

Microsoft VBScript

Microsoft® Visual Basic® Scripting Edition Conventions de codage de VBScript  Didacticiel VBScript 
 Précédent
Suivant

 

Qu'entend-on par conventions de codage ?
Ces conventions sont des suggestions pouvant simplifier l'écriture de code avec Microsoft Visual Basic Scripting Edition. Elles incluent notamment :
  • des conventions d'affectation de noms à des objets, des variables et des procédures,
  • des conventions de commentaire,
  • des directives de mise en forme et de mise en retrait.
L'utilisation de conventions cohérentes vise principalement à normaliser la structure et le style de codage d'un script ou d'un jeu de scripts pour rendre le code plus lisible et mieux compréhensible. L'emploi de conventions de codage appropriées permet de créer un code source précis, lisible, intuitif, ne présentant aucune ambiguïté, et respectant les conventions des autres langages.
Conventions d'affectation de noms à des constantes
Les versions précédentes de VBScript n'avaient pas de mécanisme de création de constantes définies par l'utilisateur. Les constantes, si elles étaient utilisées, étaient mises en œuvre comme des variables et distinguées des autres variables grâce à une syntaxe en caractères majuscules. Les différents mots étaient séparés par le caractère de soulignement (_). Par exemple :
 MAX_LISTE_UTILISATEUR
 SAUT_DE_LIGNE
Bien que ce mécanisme soit toujours acceptable pour identifier vos constantes, vous pouvez utiliser un nouveau schéma de notation car il est possible de créer de véritables constantes avec l'instruction Const. Cette convention utilise un format mixte, dans lequel les noms de constante commencent par le préfixe "con". Par exemple :
 conVotrePropreConstante
Conventions d'affectation de noms à des variables
Pour assurer lisibilité et cohérence, utilisez dans votre code VBScript les préfixes présentés dans le tableau suivant, avec des noms de variable descriptifs.

Sous-type Préfixe Exemple
Boolean bln blnTrouvé
Byte byt bytDonnéesRaster
Date (Time) dtm dtmDébut
Double dbl dblTolérance
Error err errNumOrdre
Integer int intQuantité
Long lng lngDistance
Object obj objCourant
Single sng sngMoyenne
String str strPrénom

Portée des variables
La portée des variables doit toujours être la plus petite possible. Les variables VBScript peuvent avoir la portée suivante.

Portée Endroit de déclaration de la variable Visibilité
Niveau procédure Procédure Event, Function ou Sub Visible dans la procédure où elle est déclarée
Niveau script Section HEAD d'une page HTML, hors de toute procédure Visible dans toutes les procédures du script
Préfixes de portée de variable
Plus la taille du script augmente, plus il devient indispensable de pouvoir différencier rapidement la portée des variables. Un préfixe d'une lettre placé devant le préfixe de type assure cette différenciation, sans trop augmenter la taille des noms de variable.

Portée Préfixe Exemple
Niveau procédure Aucun dblVélocité
Niveau script s sblnCalculEnCours

Noms descriptifs de variable et de procédure
Le corps d'un nom de variable ou de procédure doit être composé de lettres minuscules et majuscules et décrire sa fonction. En outre, les noms de procédure doivent commencer par un verbe, tel que InitialiserTableau ou FermerDialogue.

Dans le cas de termes longs ou fréquemment utilisés, il est préférable d'employer des abréviations normalisées pour maintenir une longueur de nom raisonnable. Pour assurer la lisibilité du code, il est généralement préférable d'utiliser des noms de variable de moins de 32 caractères. Lors de l'emploi d'abréviations, assurez-vous que celles-ci sont cohérentes dans tout le script. Par exemple, l'utilisation aléatoire de Ctr et Compteur dans un script ou un ensemble de scripts peut créer une confusion.

Conventions d'affectation de noms à des objets
Le tableau suivant présente les conventions recommandées pour les divers objets utilisables en programmation VBScript.

Type d'objet Préfixe Exemple
Panneau 3D pnl pnlGroupe
Bouton animé ani aniBoîteALettre
Case à cocher chk chkLectureSeule
Liste modifiable, zone de liste déroulante cbo cboAnglais
Bouton de commande cmd cmdQuitter
Boîte de dialogue commune dlg dlgFichierOuvrir
Cadre fra fraLangage
Barre de défilement horizontale hsb hsbVolume
Image img imgIcône
Étiquette lbl lblMessageAide
Ligne lin linVerticale
Zone de liste lst lstCodesEmplois
Compteur spn spnPages
Zone de texte txt txtNom
Barre de défilement verticale vsb vsbVitesse
Curseur sld sldÉchelle

Conventions pour les commentaires dans le code
Toutes les procédures doivent commencer par un bref commentaire décrivant leur action. Cette description doit exclure les détails de mise en œuvre (techniques employées) parce que ceux-ci sont sujets à modification et pourraient imposer une gestion de commentaire inutile ou pire, devenir erronés. La mise en œuvre est décrite par le code lui-même et d'éventuels commentaires sur une ligne.

Les arguments passés à une procédure doivent être décrits lorsque leur fonction n'est pas évidente et qu'ils doivent être compris dans une plage spécifique. Les valeurs de retour des fonctions et les variables modifiées par une procédure, notamment par l'intermédiaire d'arguments de référence, doivent également être décrites au début de chaque procédure.

Les commentaires des en-têtes de procédure doivent inclure les titres de section suivants. La section suivante, "Mise en forme du code", vous présente des exemples.

Titre de section Contenu des commentaires
Objet Ce que fait la procédure (et non comment elle le fait).
Commentaires Liste de variables, contrôles, ou autres éléments externes dont l'état a une incidence sur cette procédure.
Effets Présentation de l'effet de la procédure sur les variables, contrôles ou autres éléments externes.
Entrées Explication de tous les arguments non évidents. Entrez une ligne de commentaire distincte pour chaque argument.
Valeurs renvoyées Explication de la valeur renvoyée.
N'oubliez pas :
  • Pour chaque déclaration de variable importante, prévoyez un commentaire sur une ligne décrivant l'utilisation.
  • Les noms des variables, contrôles et procédures doivent être suffisamment clairs pour que les commentaires sur une ligne servent uniquement à fournir des détails de mise en œuvre complexe.
  • Entrez au début de votre script une présentation générale, décrivant le script, énumérant les objets, les procédures, les algorithmes, les boîtes de dialogue et les autres dépendances système. Il peut parfois être utile d'inclure un peu de pseudocode décrivant l'algorithme.

Mise en forme du code
Bien que la mise en forme doive refléter la structure logique et l'imbrication du code, il convient d'économiser au maximum l'espace écran. Voici quelques conseils à cet égard :
  • Les blocs imbriqués standard doivent être mis en retrait de quatre espaces.
  • Les commentaires généraux d'une procédure doivent être mis en retrait d'un espace.
  • Les instructions du plus haut niveau venant après les commentaires généraux doivent être mises en retrait de quatre espaces, chaque bloc imbriqué étant lui-même mis en retrait de quatre espaces supplémentaires. Par exemple :

 '*********************************************************
 ' Objet:    Trouve la première occurrence d'un utilisateur 
 '           spécifié dans le tableau ListeUtilisateurs.
 ' Entrées:  strListeUtilisateurs(): liste des utilisateurs 
 '           dans laquelle effectuer la recherche.
 '           strUtilisateurCible: nom de l'utilisateur à 
 '           rechercher.
 ' Retours:  L'index de la première occurrence de 
 '           strUtilisateurCible dans le tableau 
 '           ListeUtilisateurs. 
 '           Si l'utilisateur cible est introuvable, 
 '           renvoie -1.
 '*********************************************************

 Function intChercherUtilisateur (strListeUtilisateurs(), strUtilisateurCible)
     Dim i                     ' Compteur de boucle.
     Dim blnTrouvé	       ' Indicateur de cible trouvée
     intChercherUtilisateur = -1
     i = 0               ' Initialiser le compteur de boucle
     Do While i <= Ubound(strListeUtilisateurs) and Not blnTrouvé
         If strListeUtilisateurs(i) = strUtilisateurCible Then 
             blnTrouvé = True   ' Indicateur à True
             intChercherUtilisateur = i ' Définir valeur retour compteur de boucle
         End If
         i = i + 1             ' Incrément compteur de boucle
     Loop
 End Function