web-dev-qa-db-fra.com

Comment commenter une structure if-else?

Disons que vous avez:

if(condition) {
    i = 1;
} else {
    i = 2;
}

et vous devez mettre des commentaires expliquant les blocs if et else. Quelle est la manière la plus lisible de le faire pour que quelqu'un puisse facilement les récupérer au premier coup d'œil?

Je le fais habituellement comme ceci:

//check for condition
if(condition) {
    i = 1;
} else {
    //condition isn't met
    i = 2;
}

ce que je trouve pas assez bon car les commentaires sont situés à différents niveaux, donc à un coup d'œil, vous devriez simplement prendre if commentaire et else commentaire ressemblerait à une structure interne.

Les mettre comme ça:

if(condition) {
    //check for condition
    i = 1;
} else {
    //condition isn't met
    i = 2;
}

ne me semble pas bien non plus car il semblerait que la structure entière ne soit pas commentée (la condition peut être grande et prendre plusieurs lignes).

Quelque chose comme ca:

//check for condition
if(condition) {
    i = 1;
//condition isn't met
} else {
    i = 2;
}

serait probablement le meilleur style du point de vue des commentaires mais déroutant en tant que structure de code.

Comment commentez-vous ces blocs?

PS. Je ne demande pas la refactorisation de ces deux lignes de code, seulement le style de code et la mise en forme des commentaires.

coding-stylecomments
69
serg

S'il est nécessaire de commenter les instructions if else, je préfère décrire le cas qui a permis au code d'atteindre ce point. Surtout dans le code à haute complexité cyclomatique

if (condition) { 
// User is taking a course at college x:
    i = 1;
} else { 
// User is not taking any course at college x:
    i = 2;
}
31
MrBliss

Une autre option est:

if(condition) { //check for condition
    i = 1;
} else { //condition isn't met
    i = 2;
}
23
David Johnstone

Vous ne devez annoter que si le code n'est pas explicite. Alors faites le si explicite. Comme ça peut-être

bool fooIsNotReallyGood = ....;

if(fooIsNotReallyGood) {
...
} else {
...
}
13
Preet Sangha

Si le code n'est pas déjà auto-documenté, je le structurerais comme suit:

if (someCondition) {
    // If some condition, then do stuff 1.
    doStuff1();
}
else {
    // Else do stuff 2.
    doStuff2();
}

Mais encore une fois, cela n'a pas beaucoup de sens si le code est déjà auto-documenté. Si vous souhaitez ajouter des commentaires en raison d'une condition complexe comme:

if (x == null || x.startsWith("foo") || x.endsWith("bar") || x.equals("baz")) {
    doStuff1();
}
else {
    doStuff2();
}

Ensuite, je considérerais de le refactoriser comme:

boolean someCondition = (x == null || x.startsWith("foo") || x.endsWith("baz") || x.equals("waa");

if (someCondition) {
    doStuff1();
} else {
    doStuff2();
}

Dans lequel le nom de variable someConditionen fait résume l'ensemble de la condition en un mot. Par exemple. usernameIsValid, userIsAllowedToLogin ou plus.

10
BalusC

Optez pour des conditions d'auto-commentaire, puis des commentaires supplémentaires ne sont pas nécessaires. Disons que la condition est que le prêt maximum à la valeur soit atteint. Cela nous donne:

if (maximumLoanToValueIsReached)
{
   i=1;
}
else
{
   i=2;
}

Pas besoin de spécifier quand i = 2 que le prêt maximum à la valeur n'a pas été atteint car cela va de soi. En passant, je renommerais également i en quelque chose de plus significatif.

5
Chris Knight

Je ne ferais aucun commentaire dans ces cas particuliers - les commentaires n'ajoutent aucune valeur à votre code déjà clair. Si vous avez une condition vraiment complexe qui est difficile à lire, j'envisagerais de la factoriser dans une fonction (probablement inline) avec un nom très propre.

4
sblom

//condition isn't met semble être un commentaire inutile. Mais dans le cas où un tel commentaire est requis, je le fais comme ceci (C #):

//check for condition
if(condition) 
{
    i = 1;
} 
//some other condition
else 
{
    i = 2;
}

Cependant, si le bloc est juste si-sinon, je fusionnerais les deux commentaires avant si.

Pour javascript je préfère

//check for condition
if(condition) {
    i = 1;
} else { //some other condition
    i = 2;
}

P.S. Il semble qu'il y ait autant d'opinions qu'il y a de gens :)

2
Egor Pavlikhin

C'est ainsi que je fais mes commentaires pour les déclarations if then, bien que je trouve généralement que ce n'est pas nécessaire. J'aime le mettre en ligne avec le if/else, et tabulé au même endroit

if ( condition )    //if above the bar
{
    i = 0;
    k = 1;
}
else                //else if below
{
    i = 1;
    k = 2;
}
2
Justen

Les commentaires sont très personnels et (comme le montrent certaines des réponses précédentes) suscitent autant de débats que le code.

Dans les cas simples, les commentaires nuisent au code. Mais en supposant une condition plus complexe, je préfère:

/*
** Comment explaining what the condition
** is trying to determine
*/
if ( condition )
{
    /*
    ** Comment explaining the implications
    ** of the condition being met
    */
    do_something();
}
else
{
    /*
    ** Comment explaining the implications
    ** of the condition not being met
    */
    do_something_else();
}

Dans tous les cas, les commentaires ne doivent pas simplement répéter le code.

1
Andrew

Les variables sont importantes, pas les conditions elles-mêmes.

if condition: # <condition dependent variable> was <predicated>
  dosomething()
Elif othercondition: # <othercondition dependent variable> <predicated>
  dootherthing()
else: # <all variables> <not predicated>
  doelsething()
1
Ignacio Vazquez-Abrams

Il n'y a pas de réponse unique - différentes personnes auront des opinions différentes sur ce qui est le plus lisible. Cependant, je pense qu'il y a accord sur le fait que les commentaires devraient réellement ajouter de la valeur au code (sinon explicite) et que le style de commentaire devrait être cohérent.

La façon dont je gère les commentaires pour les conditions qui ne s'expliquent pas immédiatement est la suivante:

  // If the condition for a local tree imbalance is met,
  // juggle the immediate nodes to re-establish the balance.
  // Otherwise, execute a global balancing pass.
  if ( somewhat muddled condition )
  {
     ...code...
  }
  else // Tree is in local balance
  {
     ... more code...

  } // if/else (tree locally imbalanced)

Le commentaire sur le '}' final existe principalement pour donner plus de poids visuel à la fin de la condition, pour faciliter la lecture à travers la source.

1
Lars