Where to put comments in an if-then-else construct

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

// 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 2

I'd do case a) but with an extra bit of whitespace:

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

Use what makes sense to you, I guess (unless you're working under a coding standard that specifies commenting style). Personally I don't use (c) because it's inconsistent between the first and following cases. I do occasionally use (b) when a short comment will do but generally I prefer (a). If I'm commenting several sub-blocks within the if block, I might leave a blank line after the case comment:

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

and so on.

Answer 4

just to add the missing answer for the else's comment placement, which in my opinion is the best placement for code readability for the following reasons:

• if the comment is put above the else it breaks the if-else continuity
• if put inside it can mixes with the comment of the first statement inside the else

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

It looks really good if you collapse the blocks

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

Answer 5

I never gave it very much thought; personally and when required I have put comments above the IF and ELSE statements. This gives me nice separation between the comments about the branch statements and comments about the code.

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

I also note that I am the only answer so far to use the "open curly brace style", which might be a throw back to my Pascal days although I do prefer the visual justification of begin and ends of code blocks, so my comment style may not work for the "closed curly brace style community.

Answer 6

Personally, I findi it better to write code that doesn't require little comments that say "about do do x", followed by "DoX()". If necessary, rather than write a comment saying "do x because of y", I'd prefer to write a method named "DoXBecauseOfY". If later refactoring removes the "BecauseOfY" part, then it still makes better sense to put a comment before the if statement, documenting the overall logic.

Of course, you then need to reduce the amount of code within each branch to the point where you can read the entire if statement at once.