INFO : Conventions d'affectation de noms de MCS (Microsoft Consulting Services) pour Visual Basic

Il est judicieux d'établir des conventions d'affectation de noms pour votre code Visual Basic. Cet article vous donne les conventions d'affectation de noms utilisées par MCS (Microsoft Consulting Services).

Il rassemble les conventions de codage de Visual Basic que vous pouvez trouver dans le Guide du programmeur Visual Basic.

REMARQUE : Les contrôles tiers mentionnés dans cet article sont fabriqués par des fournisseurs indépendants de Microsoft. Microsoft exclut toute garantie, implicite ou autre, concernant les performances ou la fiabilité de ces contrôles.

Les conventions d'affectation de noms aident les programmeurs de Visual Basic à :

• normaliser la structure, le style de codage et la logique d'une application.
• créer un code source précis, lisible et non ambigu.
• être cohérent avec les conventions d'autres langages (notamment le Guide du programmeur Visual Basic et la notation hongroise Windows C standard).
• être efficace du point de vue de la longueur des chaînes et du travail, offrant ainsi plus de possibilités pour des noms d'objets plus longs et plus complets.
• définir les exigences minimales nécessaires pour atteindre les objectifs ci-dessus.

Définition des options de l'environnement

Utilisez Option Explicit. Déclarez toutes les variables pour réduire le temps de programmation en diminuant le nombre de bogues causés par les fautes de frappe (par exemple, aUserNameTmp, sUserNameTmp et sUserNameTemp). Dans la boîte de dialogue Options d'environnement, définissez Déclaration des variables obligatoire sur Oui. L'instruction Option Explicit requiert la déclaration de toutes les variables dans votre programme Visual Basic. Enregistrez les fichiers en texte ASCII. Enregistrez les fichiers de feuille (.FRM) et de module (.BAS) en texte ASCII pour faciliter l'utilisation des systèmes de contrôle de version et minimiser les problèmes liés aux altérations du disque. De plus, vous pouvez :

• utiliser votre propre éditeur
• utiliser des outils automatisés, tels que grep
• créer la génération de code ou les outils CASE pour Visual Basic
• effectuer une analyse externe de votre code Visual Basic

Pour que Visual Basic enregistre toujours vos fichiers en texte ASCII, définissez l'option Format d'enregistrement par défaut sur Texte dans la boîte de dialogue Options d'environnement.

Conventions d'affectation de noms d'objets pour les objets standard

Les tableaux suivants définissent les préfixes des noms d'objets standard de MCS. Ces préfixes sont cohérents avec ceux qui figurent dans le Guide du programmeur Visual Basic.

Convention d'affectation de noms d'objets pour les objets de base de données

REMARQUE : L'utilisation d'un suffixe pour les requêtes permet à chaque requête d'être triée avec sa table associée dans les boîtes de dialogue Microsoft Access (Ajouter une table, Lister les tables Snapshot).

Conventions d'affectation de noms des menus

Les applications utilisent fréquemment de très nombreux contrôles Menu. Par conséquent, vous devez utiliser un jeu différent de conventions d'affectation de noms pour ces contrôles. Les préfixes des contrôles Menu doivent être étendus au-delà de l'étiquette mnu initiale par l'ajout d'un préfixe supplémentaire pour chaque niveau d'imbrication, avec la légende de menu finale à la fin de la chaîne du nom. Par exemple : Lorsque cette convention est utilisée, tous les membres d'un groupe de menus particulier sont listés les uns à côté des autres dans les zones de liste déroulantes d'objets (dans la fenêtre de code et la fenêtre des propriétés). De plus, les noms des contrôles de menu documentent clairement les éléments des menus auxquels ils se rapportent.

Conventions d'affectation de noms des menus pour les autres contrôles

Pour les nouveaux contrôles qui ne sont pas énumérés ci-dessus, essayez de trouver un préfixe unique de trois caractères. Cependant, il est plus important d'être clair que d'adhérer à tout prix à la règle des trois caractères.

Pour les contrôles dérivés, tels qu'une zone de liste améliorée, étendez les préfixes ci-dessus de sorte qu'il n'y ait pas de confusion quant au contrôle réellement utilisé. Une abréviation du fabricant en minuscules pourrait aussi être ajoutée au préfixe. Par exemple, vous pouvez utiliser un préfixe fra3d pour une instance de contrôle créée à partir du cadre 3D de Visual Basic Professional pour éviter toute confusion quant au contrôle réellement utilisé. Vous pouvez utiliser cmdm pour un bouton de commande MicroHelp pour le différencier d'un bouton de commande standard (cmd).

Contrôles tiers

Chaque contrôle tiers utilisé dans une application doit être énuméré dans la section de commentaires de présentation de l'application, donnant le préfixe utilisé pour le contrôle, le nom complet du contrôle et le nom du fournisseur de logiciel :

Affectation de noms des variables et des routines

Les noms des variables et des fonctions ont la structure suivante : <préfixe><corps><qualificateur><suffixe> Préfixes :

Les tableaux suivants définissent les préfixes des variables et des noms de fonction qui sont basés sur la notation C hongroise pour Windows. Ces préfixes doivent être utilisés avec toutes les variables et les noms de fonction. L'utilisation des anciens suffixes Basic (tels que %, &, #, etc.) est déconseillée.

Préfixes des variables et des noms de fonction : REMARQUE : Les valeurs dans la colonne Convergé correspondent aux efforts conjugués pour réunir les affectations de noms standard de Visual Basic, Visual Basic for Applications et Access Basic. Il est probable que ces préfixes deviendront des standards Microsoft dans un avenir proche.

Préfixes de portée et d'utilisation : La notation hongroise est aussi utile en Visual Basic qu'en C. Bien que les suffixes Visual Basic indiquent le type de données d'une variable, ils n'expliquent ni comment une variable ou une fonction est utilisée, ni la manière dont il est possible d'y accéder. En voici quelques exemples : Chacun de ces noms de variables a une signification très différente pour un programmeur. Ces informations sont perdues lorsque le nom de la variable est réduit à Send%. Les préfixes de portée tels que g et m permettent aussi de réduire le problème lié aux conflits de noms, surtout dans des projets impliquant plusieurs développeurs.

La notation hongroise est aussi largement utilisée par les programmeurs en Windows C et est constamment référencée dans la documentation des produits Microsoft et dans les livres de programmation de l'industrie. De plus, les relations entre les programmeurs en C et les programmeurs en Visual Basic pourront se renforcer à mesure que le système de développement Visual C++ prend de la vitesse. Cette transition permettra à de nombreux programmeurs en Visual Basic de passer au C pour la première fois et à de nombreux développeurs de se déplacer fréquemment entre les deux environnements.

Corps d'une variable et noms de routines

Le corps d'une variable ou le nom de routine doit utiliser des majuscules et des minuscules et décrire son objectif, peu importe sa longueur. De plus, les noms de fonction doivent commencer par un verbe, tels que InitNameArray ou CloseDialog.

Pour les termes longs ou fréquemment utilisés, il est recommandé d'utiliser des abréviations standard pour que la longueur des noms reste raisonnable. En général, les noms de variables dont la longueur est supérieure à 32 caractères peuvent être difficiles à lire en mode VGA.

Lorsque vous utilisez des abréviations, assurez-vous qu'elles sont cohérentes tout au long de l'application. En choisissant au hasard Cnt ou Count dans un projet, vous créerez une confusion inutile.

Qualificateurs sur les noms de variables et de routines

Les variables et les routines associés servent souvent à gérer et à manipuler un objet courant. Dans ces cas, utilisez des qualificateurs standard pour étiqueter les variables et les routines dérivées. Bien qu'il puisse paraître bizarre de placer le qualificateur après le corps du nom (comme dans sGetNameFirst, sGetNameLast au lieu de sGetFirstName, sGetLastName), cette pratique permet d'organiser ces noms ensemble dans les listes de routine de l'éditeur Visual Basic, facilitant ainsi la compréhension de la logique et de la structure de l'application. Le tableau suivant définit les qualificateurs courants et leur signification standard :

Types définis par l'utilisateur

Déclare des types définis par l'utilisateur en majuscules avec _TYPE ajouté à la fin du symbole. Par exemple : En déclarant une variable d'instance d'un type défini par l'utilisateur, ajoutez un préfixe au nom de la variable pour référencer le type. Par exemple :

Constantes d'affectation de noms

Le corps des noms de constantes doit être en MAJUSCULES et comporter des caractères soulignés (_) entre les mots. Bien que les constantes en Visual Basic n'incluent pas d'informations en notation hongroise, les préfixes (tels que i, s, g et m) peuvent être très utiles pour comprendre la valeur et la portée d'une constante. Pour les noms de constantes, suivez les mêmes règles que pour les variables. Par exemple :

Type de données Variant

Si vous savez qu'une variable enregistrera toujours des données d'un type particulier, Visual Basic peut traiter ces données plus efficacement si vous déclarez une variable de ce type.

Cependant, le type de donnée Variant peut être extrêmement utile lorsque vous travaillez avec des bases de données, des messages, DDE ou OLE. De nombreuses bases de données autorisent la valeur NULL comme étant valide pour un champ. Votre code doit faire la distinction entre NULL, 0 (zéro) et "" (chaîne vide). Très souvent, ces types d'opérations peuvent utiliser une routine de service générique qui n'a pas besoin de connaître le type de données reçu pour traiter ou passer les données. Par exemple : L'utilisation de ce type de données présente cependant quelques inconvénients. Les instructions de code qui utilisent des variantes peuvent être ambiguës pour le programmeur. Par exemple : Les exemples ci-dessus seraient moins ambigus et plus facile à lire, à déboguer et à maintenir si les routines de conversion de type Visual Basic étaient utilisées. Par exemple :

Commentaire de votre code

Toutes les procédures et les fonctions doivent commencer par un bref commentaire décrivant les caractéristiques fonctionnelles de la routine (ce q'elle fait). Cette description ne doit pas inclure les détails de l'implémentation (comment elle le fait) car ceux-ci changent souvent au cours du temps, entraînant une maintenance inutile des commentaires ou, pire encore, des commentaires erronés. Le code en lui-même et tout commentaire local ou dans la ligne nécessaire décriront l'implémentation.

Les paramètres passés à une routine doivent être décrits lorsque leurs fonctions ne sont pas évidentes et lorsque la routine s'attend à ce que les paramètres soient compris dans une plage spécifique. Les valeurs de retour de fonctions et les variables globales qui sont changées par la routine (surtout par l'intermédiaire des paramètres de référence) doivent aussi être décrites au début de chaque routine.

Les blocs de commentaires en en-tête des routines devraient ressembler à ceci (voir la section "Format de votre code" ci-après pour un exemple) : Chaque déclaration de variable complexe doit inclure un commentaire sur la ligne décrivant l'utilisation de la variable déclarée.

Les variables, les contrôles et les routines doivent être clairement nommés de sorte que les commentaires sur la ligne soient seulement nécessaires pour des détails d'implémentation non intuitifs ou complexes.

Une description d'ensemble de l'application, énumérant les objets de données primaires, les routines, les algorithmes, les boîtes de dialogue, les dépendances système des bases de données et des fichiers, et ainsi de suite, doivent être incluse au début du module .BAS contenant les déclarations des constantes génériques Visual Basic du projet.

REMARQUE : Le fenêtre Projet décrit par nature la liste des fichiers dans un projet ; cette section de présentation doit seulement fournir des informations sur les fichiers et les modules les plus importants, ou sur les fichiers non répertoriés dans la fenêtre Projet, tels que les fichiers d'initialisation (.INI) ou de base de données.

Format de votre code

De nombreux programmeurs utilisant toujours des modes d'affichage VGA, l'état de l'écran doit être conservé le plus possible, tout en veillant à ce que le code puisse être formaté pour refléter la structure logique et l'imbrication.

Les mises en retrait d'imbrication standard, tabulées ou par blocs doivent contenir entre deux et quatre espaces. Il est inutile d'utiliser plus de quatre espaces car des instructions pourraient être cachées ou tronquées accidentellement. L'utilisation de moins de deux espaces n'est pas suffisante pour indiquer l'imbrication logique. Dans la Base de Connaissances Microsoft, nous utilisons une mise en retrait de trois espaces. Utilisez la boîte de dialogue Options d'environnement pour définir la largeur de la tabulation par défaut.

Le commentaire de présentation fonctionnelle d'une routine doit être mis en retrait d'un espace. Les instructions de haut niveau qui suivent le commentaire de présentation doivent être mises en retrait d'un espace, chaque bloc imbriqué étant mis en retrait d'un espace supplémentaire. Par exemple : Les variables et les constantes non génériques divent être groupées par fonction au lieu d'être séparées dans des zones isolées ou des fichiers spéciaux. Les constantes génériques de Visual Basic telles que HOURGLASS doivent être groupées dans un module unique (VB_STD.BAS) de façon à ce qu'elles soient séparées des déclarations spécifiques à l'application.

Opérateurs

Utilisez toujours une esperluette (&) lorsque vous concaténez des chaînes et utilisez le signe plus (+) lorsque vous travaillez avec des valeurs numériques. L'utilisation du signe plus (+) avec des valeurs non numériques peut causer des problèmes en opérant sur deux variantes. Par exemple :

Portée

Les variables doivent toujours être définies avec la plus petite portée possible. Les variables globales peuvent créer des machines très complexes et rendre la logique d'une application extrêmement difficile à comprendre. Les variables globales rendent aussi la réutilisation et la maintenance de votre code plus difficiles. Les variables dans Visual Basic peuvent avoir la portée suivante : Dans une application Visual Basic, utilisez seulement des variables globales lorsqu'il n'y a pas d'autre moyen pratique de partager les données entre les feuilles. Vous pouvez considérer l'enregistrement des informations dans la propriété Tag d'un contrôle, à laquelle il est possible d'accéder globalement à l'aide de la syntaxe form.object.property.

Si vous devez utiliser des variables globales, il convient de les déclarer toutes dans un module unique et de les regrouper par fonction. Donnez au module un nom significatif qui indique son objectif, tel que GLOBAL.BAS.

À l'exception des variables globales (qui ne doivent pas être passées), les procédures et les fonctions doivent seulement s'appliquer aux objets qui leur sont passés. Les variables globales qui sont utilisées dans des routines doivent être identifiées dans la zone de commentaires d'ordre général au début de la routine. De plus, passez les arguments aux sub et aux fonctions en utilisant ByVal, à moins que vous ne souhaitiez changer la valeur de l'argument passé.

Écrivez du code modulaire chaque fois que cela s'avère possible. Par exemple, si votre application affiche une boîte de dialogue, mettez tous les contrôles et le code requis pour effectuer la tâche de la boîte de dialogue dans une feuille unique. Cela permet de garder le code de l'application organisé en composants utiles et de minimiser sa gestion d'exécution.

Contrôles tiers

REMARQUE : Les produits mentionnés ci-dessous sont fabriqués par des fournisseurs indépendants de Microsoft. Microsoft exclut toute garantie, implicite ou autre, concernant les performances ou la fiabilité de ces produits.

Le tableau suivant répertorie les préfixes des noms des fournisseurs tiers standard à utiliser avec les préfixes des contrôles : Le tableau suivant répertorie les préfixes des contrôles tiers standard :