NSG blog

Comme vous le savez peut-être, ou sinon c’est un bon moment d’en entendre parler, commenter le code est l’une des bases pour chaque bon programmeur. Bien que commenter le code peut être un gênant, vous devriez toujoursvous assurer que les commentaires sont appropriés et précis afin qu’ils soient vraiment utiles, et pas seulement des lignes supplémentaires dans le code. Ci-dessous vous trouverez quelques conseils concernant les commentaires de code ainsi que deux exemples de «bon commentaire » et un « mauvais commentaire ». Voici les directives que je propose pour devenir un meilleur écrivain de commentaires de code:

• Lorsque vous mettez les commentaires, n’oubliez pas de penser aux personnes qui vont les lire à part vous. Ce qui vous paraît logique, peut ne pas avoir de sens pour quelqu’un de nouveau sur le projet.
• N’ énoncez pas une évidence dans vos commentaires, n’expliquez pas ce que fait le code, expliquez la raison pour laquelle le code est fait. La fonctionnalité du code peut être facilement compris en suivant le code alors que le but réel, non.
• Non tout le code doit être commenté juste les parties qui exposent des fonctionnalités critiques ou une logique métier si complexe qu’il exige une explication.
• Lorsque vous trouvez un bug dans votre code ou dans le code de quelqu’un d’autre, réparez le,  s’il est impossible pour le moment, expliquez vos solutions de contournement dans les commentaires, avec cela, si  quelqu’un le lit, il/elle comprendra pourquoi vous avez fait de cette façon. Et si plus tard, on veut utiliser le même composant défectueux ou retirer la solution de contournement, on peut facilement trouver soit le bon endroit ou la bonne solution.
• Les commentaires de code peuvent être également utilisés pour regrouper les tâches au sein de notre code, si votre code fait ce type de regroupement, place un commentaire au début de la tâche afin que le lecteur sache que les lignes ci-dessous se réfèrent tous au même workflow de traitement.
• En commentant certains comportements spécifiques ou workflow vos commentaires, vos commentaires peuvent croître assez facilement. Quand cela arrive, couper votre commentaire toutes les quelques mots et continuer sur la ligne ci-dessous, de sorte qu’il est facile à lire, car plusieurs études ont montré que nos yeux sont plus à l’aise lors de la lecture des lignes courtes.
• Si vous avez un code qui a encore besoin de travail, marquez le avec un commentaire en commençant par un « TODO: ». De cette façon, il est plus facile de suivre et de faire un suivi. Personne ne voudrait diffuser du code avec les tâches en attente sur elle.
• N’utilisez pas la syntaxe multiligne pour votre code (/ * … * /), utilisez, au lieu, la syntaxe seule ligne  (/ /), il est plus facile de travailler avec, et dans le cas où vous avez les caractères spéciaux (* /) dans votre code vous ne perdez pas du temps à sa recherche. Visual Studio dispose d’une fonction pour commenter plusieurs lignes au cas où vous ne voulez pas passer du temps à aller ligne par ligne.
• Ne placez pas vos commentaires à la fin de la ligne, mettez le au-dessus du code. Les commentaires qui sont à la fin de la ligne sont difficiles à lire et à trouver, spécialement si le code est lu dans les petits écrans.

 [error]Exemple de mauvais commentaires:[/error]

foreach (string word in Sentence) // Cycle through all words in sentence
{
// Initialize word formatter with 0
WordFormatter formatter = new WordFormatter(0);
// Initialize word formatter with 125
formatter = new WordFormatter(125);

// Review word
formatter.Review(word);
    // Invert word
string invertedWord = formatter.Invert(word);
   // Review inverted word
formatter.Review(invertedWord);
// Need to complete code for tracking the words that didn’t passed the review.
}

[important]Exemple de bon commentaires[/important]

// For every word we have in the sentence
// we need to pass it through the formatter
// in order to find invalid chars, bad language
// or words that are under copyright.
foreach (string word in Sentence)
{
   // There’s a bug that sometimes prevents the initialzer
// from working properly the first time is used
// as a workaround we intialize it with a dummy value (0)
// then we use our project formatter code (125)
WordFormatter formatter = new WordFormatter(0);
formatter = new WordFormatter(125);

  // The main flow requires us to review the word
// then invert it and review the inverted word
// as per business requirement.
formatter.Review(word);
string invertedWord = formatter.Invert(word);
formatter.Review(invertedWord);
// TODO: Add logic for keeping track words that
// didn’t passed the review.
}