Where to put comments in an if-then-else construct? [closed]

Question

I never decided on what the best way is to comment if-then-else constructs, so I never standardized on a consistent way to comment them. I appreciate any insights.

Some 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(); } 

drawback: in case of multiple dothis() statements, I like to comment the major blocks, and in that case it isn't always clear if the IF-comment belongs to the first dothis() block or to the whole IF case

or 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: only works for short comments. I usually comment IF-THEN-ELSE constructs if the IF and ELSE case isn't directly clear from the code, which typically requires a comment longer than one line.

or c)

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

PS: I know about "the code should be self explanatory", but this isn't always the case...

Answer 1

For me, a comment above the IF explains the IF statement itself. For example, if the condition being tested is particularly complex.

A comment in the block below the IF or ELSE describes what's going once the condition has been evaluated and a choice made.

So like this:

//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); }