Où placer des commentaires dans une construction IF THEN ELSE

Question

Je n'ai jamais décidé de la meilleure façon de commenter IF-THEN-ELSE, donc je n'ai jamais standardisé de manière cohérente pour les commenter. J'apprécie toute idée.

Certaines options:

a)

IF (blabla) { 
    // this comment explains what happens in the IF case 
    dothis(); 
} else { 
    // this comment explains what happens in the ELSE case 
    dosomethingelse(); 
} 

inconvénient: en cas de multiples déclarations dothis(), je voudrais commenter les grands blocs, et dans ce cas il est pas toujours clair si l'IF-commentaire appartient au premier dothis() bloc ou à l'ensemble SI cas

ou b)

IF (blabla) { // this comment explains what happens in the IF case 
    dothis(); 
} else { // this comment explains what happens in the ELSE case 
    dosomethingelse(); 
} 

drawback: ne fonctionne que pour les commentaires courts. J'ai l'habitude de commenter IF-THEN-ELSE construit si le cas IF et ELSE n'est pas directement clair du code, qui exige typiquement un commentaire plus long qu'une ligne.

ou c)

// if the following happens 
IF (blabla) { // then do this 
    dothis(); 
} else { // or else do this 
    dosomethingelse(); 
} 

PS: Je sais "le code doit être explicite", mais ce n'est pas toujours le cas ...

Answer 1

Pour moi, un commentaire au-dessus du IF explique l'instruction IF elle-même. Par exemple, si la condition testée est particulièrement complexe.

Un commentaire dans le bloc ci-dessous le IF ou ELSE décrit ce qu'il se passe une fois que la condition a été évaluée et qu'un choix a été fait.

donc comme ceci:

//Is this a favoured customer and do we have a promotion? 
if customer.special() and monthly.hasOffer() { 
    //Add discount 
    invoice.addDiscount(); 
} 
else { 
    //Add note about favoured customer scheme 
    invoice.addNotes(JOIN_OUR_DISCOUNT_SCHEME); 
} 

Answer 2

Je ferais le cas a), mais avec un peu plus d'espaces:

if (blabla) { 
    // This explains the whole if case 

    // Can comment here for specific block comments 
    doThis(); 
} else { 
    // This explains the else case 

    // Same again 
    doSomethingElse(); 
} 

Answer 3

Utilisez ce que vous fait sens, je suppose (à moins que vous » re travailler sous une norme de codage qui spécifie le style de commentaire). Personnellement, je n'utilise pas (c) parce que c'est incohérent entre le premier et les cas suivants. J'utilise parfois (b) quand un court commentaire fera mais en général je préfère (a). Si je commente plusieurs sous-blocs dans le bloc si, je pourrais laisser une ligne blanche après le commentaire de cas:

if (blabla) { 
    // here's a comment about this case 

    // comment about this bit of code 
    bit_of_code(); 
    // comment about this other bit of code 
    other_bit_of_code(); 
} 

et ainsi de suite.

Answer 4

Je n'y ai jamais vraiment pensé; Personnellement et si nécessaire, j'ai mis des commentaires au-dessus des déclarations IF et ELSE. Cela me donne une bonne séparation entre les commentaires sur les instructions de branche et les commentaires sur le code.

// comment about the if statement 
if (expression) 
{ 
    // comment about the code 
    doSomething(); 
} 
// comment about the else statement 
else 
{ 
    // comment about the code 
    doSomethingElse(); 
} 

Je note aussi que je suis la seule réponse à ce jour pour utiliser le « style accolade ouverte », ce qui pourrait être un jet de nouveau à mes jours Pascal, bien que je préfère la justification visuelle de commencer et la fin des Blocs de code, donc mon style de commentaire peut ne pas fonctionner pour la "communauté de style accolade fermée."

Answer 5

Personnellement, je trouve qu'il est préférable d'écrire du code qui ne nécessite pas de petits commentaires qui disent "à propos do do x", suivi par "DoX()".Si nécessaire, plutôt que d'écrire un commentaire disant «fais x à cause de y», je préférerais écrire une méthode nommée «DoXBecauseOfY». Si le refactoring ultérieur supprime la partie "BecauseOfY", il est toujours préférable de mettre un commentaire avant l'instruction si, en documentant la logique globale.

Bien sûr, vous devez ensuite réduire la quantité de code dans chaque branche au point où vous pouvez lire l'intégralité de l'instruction si à la fois.

Answer 6

// Not very much sure, but here is a snippet of my code 

// tweak URL as per query params and hash index positions 
if (hasQueryParams && hashPos > -1) { 
    // both query params and hash available 
    ... 
    ... 
} else if (hasQueryParams) { 
    // only query params available 
    ... 
    ... 
} else if (hashPos > -1) { 
    // only hash available 
    ... 
    ... 
} else { 
    // neither query params nor hash available 
    ... 
    ... 
} 

Answer 7

De l'oracle java docs pour les conventions de code

ligne unique commentaires pour if-else:

if (condition) { 
/* Here is a single line comment. */ 
... 
} 

ligne simple très court commentaires pour if-else:

if (a == 2) { 
    return TRUE; /* special case */ 
} else { 
return isprime(a); /* works only for odd a */ 
} 

ligne multi commentaires pour if-else: juste

if (condition) { 
/* 
    * Here is a block comment. 
    */ 
} 

Answer 8

pour ajouter la réponse manquante pour le placement de commentaire de l'autre, qui à mon avis est le meilleur emplacement pour la lisibilité du code pour les raisons suivantes:

• si le commentaire est mis au-dessus du reste, il brise la continuité if-else
• si mis à l'intérieur, il peut se mélange avec le commentaire de la première déclaration à l'intérieur du reste

// match jth arc 
if (j < Count) 
{ 
    // arc matched 
    if (arcs[j].IsBlue) List.Add(arcs[j]) 
} 
else // all arcs were matched 
{ 
    // check if there more arcs 
    if (arcs[j + 1] != null) continue; 
} 

Il a l'air vraiment bien si vous réduisez les blocs

// match jth arc 
if (j < Count)|...| 
else // all arcs were matched|...| 

Answer 9

Que diriez-vous de ce style? En utilisant // commentaire pour la description de l'instruction if-else entière, et /* */ commentaire pour la description interne. J'utilise /* */ pour ne pas être confondu avec le commentaire interne de l'instruction if-else.

// Process1 
    if (cond1-1) { 
     /* Process1 > Process1-1 */ 
     Process1-1(); 
     // Process1-1 description... 
     Process1-1(); 
     Process1-1(); 
     ... 

    } else if (cond1-2) { 
     /* Process1 > Process1-2 */ 
     // Process1-2 description... 
     Process1-2(); 
     Process1-2(); 
     Process1-2(); 
     ... 

     // Process1-2 
     if (cond1-2-1) { 
      /* Process1 > Process1-2 > Process1-2-1 */ 
      Process1-2-1(); 
      Process1-2-1(); 
      Process1-2-1(); 
      ... 

     } else if (cond1-2-2) { 
      /* Process1 > Process1-2 > Process1-2-2 */ 
      Process1-2-2(); 
      // Process1-2-2 description... 
      Process1-2-2(); 
      // Process1-2-2 description... 
      Process1-2-2(); 
      ... 

     } else { 
      /* Process1 > Process1-2 > Process1-2-else */ 
      Process1-2-else(); 
      Process1-2-else(); 
      Process1-2-else(); 
      ... 
     } 

    } else { 
     /* Process1 > Process1-else */ 
     Process1-else(); 
     Process1-else(); 
     Process1-else(); 
     ... 
    }