Commentaires dans le code (Visual Basic)

Lorsque vous lisez les exemples de code, vous rencontrez souvent le symbole de commentaire ('). Ce symbole indique au compilateur Visual Basic d'ignorer le texte qui le suit, c'est-à-dire le commentaire. Les commentaires sont de courtes explications destinées à éclairer ceux qui lisent le code.

En programmation, il est hautement recommandé de faire précéder toutes les procédures d'un commentaire court qui décrit les caractéristiques fonctionnelles de la procédure (ce qu'elle fait). Ceci est utile tant pour l'auteur du code lui-même que pour toute autre personne amenée à consulter le code. Vous devez séparer les détails relatifs à l'implémentation (comment la procédure fait ce qu'elle doit faire) des commentaires décrivant les caractéristiques fonctionnelles. Si vous fournissez des informations d'implémentation dans la description, n'oubliez pas de les mettre à jour lors de la mise à jour de la fonction.

Les commentaires peuvent soit suivre une instruction sur la même ligne, soit occuper une ligne entière. Ces deux cas sont illustrés par le code suivant :

' This is a comment beginning at the left edge of the screen.
text1.Text = "Hi!"   ' This is an inline comment.

Si votre commentaire doit occuper plusieurs lignes, utilisez le symbole de commentaire sur chacune d'elles, comme l'exemple ci-dessous l'illustre.

' This comment is too long to fit on a single line, so we break  
' it into two lines. Some comments might need three or more lines.

Recommandations sur le commentaire

Le tableau suivant fournit des recommandations générales sur les types de commentaires qui peuvent précéder une section de code. Il ne s'agit que de suggestions ; Visual Basic n'impose aucune règle concernant l'ajout de commentaires. Procédez de la façon que vous jugez la plus efficace pour vous et toute personne amenée à lire votre code.

Type de commentaire	Description du commentaire
Objectif	Décrit ce que fait la procédure (et non comment elle le fait)
Assumptions (Hypothèses)	Répertorie chaque variable externe, contrôle, fichier ouvert ou autre élément auquel la procédure accède.
Effects (Effets)	Répertorie chaque variable externe, contrôle ou fichier affecté, ainsi que ses effets (uniquement si ce n'est pas évident)
Inputs (Entrées)	Spécifie l'objectif attaché à l'argument
Returns (Retours)	Explique les valeurs retournées par la procédure.

N'oubliez pas :

• Pour chaque déclaration de variable importante, faites précéder d'un commentaire décrivant son utilisation.

• Les noms des variables, contrôles et procédures doivent être suffisamment clairs pour que les commentaires servent uniquement à fournir des détails d'implémentation complexes.

• Vous ne pouvez pas faire suivre une séquence de continuation par un commentaire sur la même ligne.

Vous pouvez ajouter ou supprimer les symboles de commentaires pour un bloc de code en sélectionnant au moins deux lignes de code et en choisissant les boutons Commenter la sélection () et Ne pas commenter la sélection () dans la barre d'outils Éditeur de texte.

Notes

Vous pouvez également ajouter des commentaires à votre code en faisant précéder le texte du mot clé REM.Cependant, le symbole ' et les boutons Commenter la sélection/Ne pas commenter la sélection sont plus simples à utiliser et sont moins gourmands en espace et en mémoire.

Voir aussi

Tâches

Comment : créer une documentation XML en Visual Basic

Référence

Balises XML recommandées pour les commentaires de documentation (Visual Basic)

REM, instruction (Visual Basic)

Autres ressources

Documentation de votre code avec des commentaires XML

Structure de programme et conventions de codage (Visual Basic)