RSS feedI tend to be pretty passionate about programming language coding
conventions, and communicating best practice can be difficult at times
when there’s a plethora of bad conventions out on the interwebs. And if
universities are actually teaching conventions, then they’re not
teaching them particularly well, or perhaps by lecturers with limited
real world experience.
Consider this code fragment:
// check for aaaa. We need to use bbbb because cccc doesn't dddd
if (condition1) {
// optional comment on code
..code goes here
} elseif (condition2) {
// optional comment on code
..code goes here
}
All good so far, but what if we need to comment on condition2? Not a
comment for the code contained within, but the condition itself. If code
is a narrative (as the analogy goes), then logically the code should
look like this:
// check for aaaa. We need to use bbbb because cccc doesn't dddd
if (condition1) {
// optional comment on code
..code goes here
// check eeee next, because ffff
} elseif (condition2) {
// optional comment on code
..code goes here
}
The code reads linearly, which is what we want, but the new comment in
column 1 breaks the readability. So how about indenting it?
// check for aaaa. We need to use bbbb because cccc doesn't dddd
if (condition1) {
// optional comment on code
..code goes here
// check eeee next, because ffff
} elseif (condition2) {
// optional comment on code
..code goes here
}
It reads better now from condition to condition, but our condition2
comment is now slightly out of scope and our peripheral reading. The
alternative would be to put the comment inside the code block:
// check for aaaa. We need to use bbbb because cccc doesn't dddd
if (condition1) {
// optional comment on code
..code goes here
} elseif (condition2) {
// check eeee next, because ffff
// optional comment on code
..code goes here
}
Now the code isn’t that readable because we get to condition2 and
there’s no explanation of it. Sure we could drop inside the condition to
read it, but it’s still outside the context of the if/else block, plus
it now runs into any comments for the code in the block, which would
mean either an intervening newline, or a combined comment that wouldn’t
read as clearly.
Remember that condition2 isn’t just a simple condition, we said that it
needed to be documented, probably because it needs to call a function or
perform some logic that’s not immediately obvious.
This is a good argument for using newlined elses:
// check for aaaa. We need to use bbbb because cccc doesn't dddd
if (condition1) {
// optional comment on code
..code goes here
}
// check eeee next, because ffff
elseif (condition2) {
// optional comment on code
..code goes here
}
But again, the code’s starting to split apart into illegibility, and
there’s a dozen reasons why newlined conditions are bad anyway.
One argument would be that the code needs to be rewritten so that it’s
simpler. If possible, all the comments could be pulled up into a single
pre-if comment, but the further the else is from the if, the less
readable that’s going to be. If it could be split into a switch
(depending on the language), then that would be an option.
Most switch conventions I’ve seen allow case condition comments to be
above and flush with the case statement, so that would seem to be an
argument for allowing pre-elseif comments, but indented or not?
I could only find two references to this if/else comment case on the
web. The first was on Dave Hyatt’s Surfin’ Safari blog (for WebKit), in
a post by Maciej Stachowiak:
http://webkit.org/blog/25/webkit-coding-style-guidelines/
It shows a comment above an else if condition, however, the code isn’t
clear whether the “comment on else case” (sic) is a comment on the
condition, or on the code within the else. It would seem to imply the
code inside the else, and so isn’t useful to us.
The only other reference I could find was on in the Adobe ActionScript
in Flash CS3 documentation:
The example code shows exactly what we’re talking about, and shows the
case that I’ve always used these past 30 years, an indented comment above the
else/elseif.
So assuming that the convention is that all conditionals have blocks and
that block openings must be on the same line as the condition, which
convention do or would you use?
One Comment