Ajouter des commentaires.

Pour vous; pour les autres.

Au début de chaque routine, Sub, Function, Classe , noter en commentaire ce qu'elle fait et quelles sont les caractéristiques des paramètres:

• Le résumé descriptif de la routine, la Sub ou Function.
• Une description de chaque paramètre.
• La valeur retournée s'il y en a une.
• Une description de toutes les exceptions..
• Un exemple d'utilisation
• Une explication sur le fonctionnement de la routine.

Ne pas ajouter de commentaire en fin de ligne (une partie ne sera pas visible) mais plutôt avant la ligne de code. Seule exception ou on utilise la fin de ligne: les commentaires après les déclarations de variable.

Dim i As Integer    'Variable de boucle

'Parcours du tableau à la recherche de..

For i=0 To 100

...

Paradoxalement, trop de commentaires tue le code autant que le manque de commentaires. Pour éviter de tomber dans le tout ou rien, fixons nous quelques règles:

Commentez le début de chaque Sub, Fonction, Classe

Commentez toutes les déclarations de variables

Commentez toutes les branches conditionnelles

Commentez toutes les boucles

Commentaire en Xml

On peut ajouter des commentaires en xml dans VB2005.

Exemple:

Pour une Sub: Sur une ligne blanche au dessus de la Sub Calcul, tapez "'''" (3 "'").

ou

Pour une variable: Curseur sur la variable, bouton droit puis 'Insérer un commentaire' dans le menu.

Un bloc Xml <Summary> se crée automatiquement; pour l'exemple de la Sub, ajouter 'Fonction Calculant le total'

Quand ensuite on tape le nom de la Sub , le commentaire s'affiche.

De plus Visual Basic génère automatiquement un fichier de documentation XML lorsque vous créez le projet. Ce fichier apparaît dans le répertoire de sortie de l'application sous le nom AssemblyName.xml.

Éclaircir, aérer  le code:

Ajouter quelques lignes blanches.

Décaler à droite le code contenu dans  une boucle ou une section If.. End If:

Une mise en retrait simplifie la lecture du code, par exemple :
If ... Then
    If ... Then
        ...
    Else
        ...
    End If
Else
...
End If

Éviter plusieurs instructions par ligne.

A= 2 : B= 3 : C=5   est à éviter.

Pas plus de 80 caractères par ligne.

Avant, on avait des écrans ou les lignes faisaient 80 caractères; maintenant on n'a pas de limitation mais:

Si on veut imprimer le source et que les lignes sont très longues, l'impression est illisible.

Pas plus de 50 lignes par fonction.

Cela permet de faire défiler rapidement la fonction et de la voire en totalité.

Mais parfois une fonction doit comporter un grand nombre de lignes, mais cette fonction est un tout et le 'découpage' en sous-fonctions est impossible (variable locale multiple) ou ce découpage augmente la complexité.  

Choisir les noms de procédures et de variables avec soins:

On concatène plusieurs mots pour former un nom de fonction, de variable de Classe..

Il y a 3 manières  d'utiliser les lettres capitales dans ces mots (on appelle cela la capitalisation!)

-Pascal Case:La première lettre de chaque mot est en majuscule:

 CalculTotal()

-Camel Case:La première lettre de chaque mot est en majuscule, sauf la première:

 iNombrePatient

-UpperCase: Toutes les lettres sont en majuscule:

 MACONSTANTE

 

De plus le nom doit être explicite.

Microsoft propose quelques règles:

Sub , Fonctions

Utilisez la 'case Pascal' pour les noms de routine (la première lettre de chaque mot est une majuscule).

Exemple: CalculTotal()

Évitez d'employer des noms difficiles pouvant être interprétés de manière subjective, notamment Analyse() pour une routine par exemple. 

Utilisez les verbe/nom pour une routine : CalculTotal().

Variables

Pour les noms de variables, utilisez la 'case Camel' selon laquelle la première lettre des mots est une majuscule, sauf pour le premier mot.

Exemple: iNombrePatient

noter ici que la première lettre indique le type de la variable (Integer), elle peut aussi indiquer la portée(gTotal pour une variable globale).

Évitez d'employer des noms difficiles pouvant être interprétés de manière subjective, 'YYB8' ou 'flag' pour une variable. 

Ajoutez des méthodes de calcul ( Min, Max, Total) à la fin d'un nom de variable, si nécessaire.

Les noms de variable booléenne doivent contenir Is qui implique les valeurs  True/False, par exemple fileIsFound.

Évitez d'utiliser des termes tels que Flag lorsque vous nommez des variables d'état, qui différent des variables booléennes car elles acceptent plus de deux valeurs. Plutôt que documentFlag, utilisez un nom plus descriptif tel que documentFormatType.

Même pour une variable à courte durée de vie  utilisez un nom significatif. 

Utilisez des noms de variable d'une seule lettre, par exemple i ou j, pour les index de petite boucle uniquement.

Paramètre

Pour les noms de paramètres, utilisez la 'case Camel' selon laquelle la première lettre des mots est une majuscule, sauf pour le premier mot.

Exemple: typeName

Constantes

Utiliser les majuscules pour les constantes: MYCONSTANTE

N'utilisez pas des nombres ou des chaînes littérales telles que For i = 1 To 7. Utilisez plutôt des constantes  par exemple For i = 1 To DAYSINWEEK, pour simplifier la maintenance et la compréhension.

Objet, Classe

Pour les noms de Classe, utiliser le case Pascal:

Exemple Class MaClasse

Idem pour les évènement, espace de nom, méthodes:

Exemple: System.Drawing, ValueChange..

Dans les  objets, il ne faut pas inclure des noms de classe dans les noms de propriétés Patient.PatientNom est inutile, utiliser plutôt Patient.Nom.

Les interfaces commencent par un I

Exemple: IDisposable

Pour les variables privées ou protégées d'une classe utilisez le case Camel:

Exemple: lastValue (variable protégée)

En plus pour les variables privées d'une classe mettre un "_" avant:

Exemple: _privateField

Pour une variable Public d'une classe utiliser le 'case Pascale':

Exemple  TotalAge

Tables

Pour les tables, utilisez le singulier. Par exemple, utilisez table 'Patient' plutôt que 'Patients'.

N'incorporez pas le type de données dans le nom d'une colonne. 

Divers

Minimisez l'utilisation d'abréviations. 

Lorsque vous nommez des fonctions, insérez une description de la valeur retournée, notamment GetCurrentWindowDirectory().

Évitez de réutiliser des noms identiques pour divers éléments.

Évitez l'utilisation d'homonymes et des mots qui entraînent souvent des fautes d'orthographe.

Évitez d'utiliser des signes typographiques pour identifier des types de données, notamment $ pour les chaînes ou % pour les entiers.

Un nom doit indiquer la signification plutôt que la méthode.

 

 

Notation hongroise:

La notation hongroise est une convention de nommage qui met en avant , par l'utilisation d'un préfixe, des informations sur l'objet nommé. 

La qualification de "hongroise" vient du pays d'origine de Simonyi, le créateur de ce nommage qui a travaillé chez Xerox puis Microsoft.

Il y a 2 sortes de notation hongroise:

Notation Apps:

On préfixe le nom des variables de manière a indiquer leur utilisation :

rwPosition : est une variable représentant  la position d'une ligne (row en anglais)

Notation Systems:

Cette notation consiste à faire précéder le nom de la variable d'un préfixe reflétant son type. Ce préfixe est toujours écrit en minuscule puis la première lettre suivante en majuscule.

Par exemple, la variable booléenne 'ouvert' est préfixée par un b pour indiquer un booléen : 'bOuvert'.

On peut préfixer avec le type et  (ou) la portée.

Type:

i    Integer (entier)

n    Short int (entier court)

l    Long  (entier long)

f    float= Single (nombre a virgule flottante)

d    Double (float double)

c    Char (caractère)

by   Byte (caractère non signe)

b    Boolean (booleen true/false)

s    String (chaîne de caractères)

h    Handle 

file File (fichier) 

et non utilisé en VB:

v void

w word (mot = double octet)

dw double word (double mot)

sz zero-terminated string (chaine de caracteres terminee par un char zero)

str string object (objet String)

pt   point 

rgb  rgb triplet 

Portée:

g : variable globale à une application
s : variable locale à un module.
p : variable passée en paramètre d’une fonction ou d’une méthode de classe.

Si une variable est un tableau, on ajoute le préfixe « a ».

Exemple:

Préfixe avec le type: variable nommée Ouvert de type boolean:

bOuvert.

Préfixe avec la portée: variable nommée Nom de portée globale:

gNom ou g_Nom

Variable nommée Position qui est une variable globale et une Integer.

g_iPosition

On voit qu'on peut utiliser ou non le caractère""_".

Cette notation hongroise a ses partisans et ses adversaires (nom trop complexe).

Nommage des objets visuels:  

Les objets visuels sont les boutons, les TextBox....

Il est conseillé par Microsoft de débuter le nom d’un objet visuel par un mot évoquant sa nature:

Microsoft conseille:

btn pour les Boutons

lst pour les ListBox

chk pour les CheckBox

cbo pour les combos

dlg pour les DialogBox

frm pour les Form

lbl pour les labels

txt pour les Textbox

tb pour les Toolsbar

rb pour les radiobutton

mm pour les menus

tmr pour les timers

Exemple:

btnOk  par exemple pour un bouton sur lequel il y a 'Ok'.