Chaque fois que j'écris une construction if-else-typique dans n'importe quelle langue, je me demande quelle serait la meilleure façon (en termes de lisibilité et de vue d'ensemble) d'y ajouter des commentaires. Surtout lorsque je commente la clause else, les commentaires me semblent toujours hors de propos. Disons que nous avons une construction comme celle-ci (les exemples sont écrits en PHP):

if ($big == true) {
    bigMagic();
} else {
    smallMagic()
}

Je pourrais le commenter comme ceci:

// check, what kind of magic should happen
if ($big == true) {
    // do some big magic stuff
    bigMagic();
} else {
    // small magic is enough
    smallMagic()
}

ou

// check, what kind of magic should happen
// do some big magic stuff
if ($big == true) {
    bigMagic();
}
// small magic is enough
else {
   smallMagic()
}

ou

// check, what kind of magic should happen
// if:   do some big magic stuff
// else: small magic is enough
if ($big == true) {
    bigMagic();
} else {
    smallMagic()
}

Quels sont vos exemples de bonnes pratiques pour commenter cela?

Je préfère soit:

if ($magic == big) {
    bigMagic();
}
else {
    smallMagic();
}

ou:

if ($magic == big) {
    // big magic requires a big surprise, so I'm telling you about it here
    surprisingThing();
}
else {
    // give a magical feeling even if $magic is noMagicAtAll
    smallMagic();
}

Il semble un peu idiot d'écrire un commentaire expliquant ce que votre condition vérifie, sauf si le code ne le précise pas clairement. Même alors, mieux vaut réécrire le code pour le rendre aussi clair que possible. Il en va de même pour les corps des blocs conditionnels - si vous pouvez rendre la raison de faire quelque chose évidente, faites-le au lieu de commenter.

Je ne souscris pas à la philosophie "ne jamais écrire de commentaires", mais je crois qu'il faut éviter les commentaires qui disent ce que le code devrait dire. Si vous écrivez un commentaire comme «vérifiez quel genre de magie devrait se produire» alors que le code pourrait le dire if ($magic == big) {..., les lecteurs arrêteront de lire vos commentaires très rapidement. L'utilisation de commentaires moins nombreux et plus significatifs donne à chacun de vos commentaires plus de valeur, et les lecteurs sont beaucoup plus susceptibles de prêter attention à ceux que vous écrivez.

Il est important de choisir des noms significatifs pour vos variables et fonctions. Un nom bien choisi peut éliminer le besoin de commentaires explicatifs tout au long de votre code. Dans votre exemple, $magicou peut-être $kindOfMagicsemble - t-il être un meilleur nom que $bigdepuis, selon votre exemple, c'est le "genre de magie" qui est testé, pas la "grandeur" de quelque chose.

Dites autant que possible dans le code. Enregistrez la prose pour les cas qui nécessitent plus d'explications que vous ne pouvez raisonnablement écrire dans le code.

Essayez les noms de variables explicatives

Les commentaires peuvent être excellents, mais lorsque cela est possible, rendez le code auto-documenté. Une façon de procéder consiste à utiliser des noms de variables explicatives. Par exemple, plutôt que ceci:

if (user.has_sideburns && user.can_gyrate) {
  // This user is a potential Elvis impersonator

}

Je préfère une variable nommée:

is_potential_elvis_impersonator = user.has_sideburns && user.can_gyrate

if (is_potential_elvis_impersonator) {
  ...
}

Juste pour compléter quelques commentaires:

La bonne utilisation des commentaires est de compenser notre incapacité à nous exprimer dans le code. Notez que j'ai utilisé le mot échec. C'est ce que je voulais dire. Les commentaires sont toujours des échecs. Nous devons les avoir parce que nous ne pouvons pas toujours trouver comment nous exprimer sans eux, mais leur utilisation n'est pas un motif de célébration. ( Code propre par Robert C. Martin )

BTW: Je recommande ce livre.

Les commentaires ne doivent pas paraphraser le code mais expliquent des choses qui ne sont pas dans le code (image plus grande, pourquoi, pourquoi une alternative n'a pas été choisie ...) Et votre exemple de commentaires est juste cela: paraphraser le code.

Vous pouvez parfois penser qu'une paraphrase est nécessaire au début de la elsebranche, mais c'est souvent un signe que votre thenbranche est trop grande.

Dans votre exemple spécifique, les commentaires ne sont probablement pas nécessaires. Comme l'a mentionné Caleb , si le code est clairement écrit et que les variables ont des noms sémantiques, si les instructions sont moins susceptibles d'avoir besoin de commentaires.

Comparez votre extrait avec ceci:

if ($x) {
    func1();
} else {
    func2();
}

Dans ce cas, vous voudrez certainement utiliser des commentaires pour décrire ce que x, func1 et func2 représentent (et gifler la personne qui a nommé les choses par ce schéma, surtout si c'était vous). Vous ne pouvez même pas dire si $xest censé être un booléen. Mais c'est aussi un cas où vous n'avez pas nécessairement besoin de commentaires, si vous êtes en mesure de refactoriser et de renommer.

En général, j'aime écrire des commentaires pour les blocs logiques qui décrivent des choses que le code ne peut pas lui-même. Une ligne toutes les ~ 10-20 lignes qui décrit ce que la poignée de lignes suivante accomplit à un niveau d'abstraction plus élevé (par exemple // Make the right amount of magic happenpour votre exemple) vous aidera à rester orienté et donnera à un nouvel examinateur un aperçu de ce que vous faites et quand .

En fait, j'écris souvent ces lignes simples avant de commencer à écrire du code, afin de ne pas perdre de vue le flux que le segment est censé avoir.

Enfin, si vous préférez vraiment (ou s'il y a un mandat qui nécessite) des clauses de commentaire dans un bloc if quelle que soit la lisibilité du code, je recommande:

// Broad description of block
if (something) {
    //Do this because something
    something();
} else {
    //Do this because !something
    somethingElse();
}

Je pense que c'est le plus propre, car le commentaire correspond au code auquel il se rapporte. Un commentaire décrivant ce que fait le code doit être aussi proche que possible du commentaire qu'il décrit.

if (IsWeekDay(day))
{// weekday -> alarm at 7am
   ...
}
else if(day == DayOfWeek.Saturday)
{// saturday -> alarm at 11am
   ...
}
else
{// (sunday) -> no alarm
   ...
}

Je garde mes supports alignés et je les place juste après le support.

[Condition] -> [pseudo-code]

Sur un autre, cela signifie techniquement que toutes les autres conditions ont échoué, donc j'utilise généralement des parenthèses.

([Condition]) -> [pseudo-code]

Remarque: c'est pour C #.

J'essaie d'utiliser des commentaires à l'intérieur du bloc en disant ce que fait ce bloc (votre premier échantillon).

Là où ça tombe en panne, c'est lors de l'utilisation elseif. J'utilise Basic, donc il n'y a pas de bloc de fin explicite et je dois souvent commenter la condition qui vérifie ce qui se passe sur la ligne ci-dessus (avec un saut de ligne bien sûr) si c'est trop long.

'Check XYZ
If Condition1 then
  'We need to do T and S
  DoCodeFor1();

'Check ABC
ElseIf Condition1 then
  'This requires something else to be done
  DoCodeFor2()

Else
  'We have no other option than to...
  DoCodeFor3()

End If

• Gardez vos blocs conditionnels très courts.
• Appelez une méthode avec un joli nom descriptif s'il semble que votre code conditionnel sera plus qu'une simple ligne ou deux.
• Utilisez de beaux noms descriptifs pour vos variables.
• Assurez-vous que l'énoncé conditionnel est clair dans sa signification, et non obscurci ou long. Utilisez une méthode si elle permet de garder les choses propres et lisibles.

Si tout ce qui précède échoue, ajoutez un très petit commentaire descriptif avant l'instruction if, pour clarifier votre intention. Sinon, il ne devrait vraiment pas être nécessaire de commenter du tout.

En C ++ ou C #, je ne commenterais généralement pas les cas simples (quand c'est clair ce qui se passe), et j'utilise ce genre de style pour commenter le reste ...

if (pattern == AAA)
{
  DoSomethingAAA();
}
else if (pattern == BBB)
{
  DoSomethingBBB();
}
else // if (pattern == CCC)
{
  DoSomethingCCC();
}