Should we be adding comments after code blocks, rather than before?

Question

This post (When not to comment code) has a great discussion about commenting styles.

I agree with the sentiment to commenting the intent of the code ("why") rather than the "what".

It occurred to me that perhaps we should be placing the comments after the code, like this:

        _checkForUpdatesThread = new Thread(new ThreadStart(updateManager.CheckForUpdates));
        _checkForUpdatesThread.Start();
        // since CheckForUpdates() can take up to a minute to execute

Rather than:

        // Start CheckForUpdates() on its own thread, since it can take up to a minute to execute
        _checkForUpdatesThread = new Thread(new ThreadStart(updateManager.CheckForUpdates));
        _checkForUpdatesThread.Start();

This allows the reader to skim through the code, concentrating on the actual code first - which is hopefully so beautiful that no-one needs to look down at the comments. If the reader finds themselves asking "Why the hell?!?" they can look down to the comments to see what the original author was thinking.

To help enforce the comment providing intent ("why"), it may be useful to always start the comment with "because", "since", "as", "instead of" or similar.

Has anyone seen this done in practice? Any thoughts on whether it's a good idea?

Answer 1

I prefer the comments being above, almost like some kind of heading, explaining the reasoning behind the code to come. But it's all about opinion really, there's no "right way".

Answer 2

It's an interesting idea, not sure if I like it though. The "standard" way goes, you say what is going to happen, you show how it happens and so forth. The other way around, when you read the comment the context is gone, the thing already happened. However, I would go for an after the fact comment that explains what should have happened at that point.

Answer 3

This is pretty much a subjective discussion, though I think comments should be above code. For the last few years I have only seen comments before code. Javadoc and doxygen api comments always precede code. For very short reasoning, sideways comments are also fairly readable.

Answer 4

I find comments before better, because if I can't explain the code before I write it, then I am not writing it properly.

Answer 5

Definitely should be above IMHO.

I look at it this way, if you have to include comments and your code is not self-explanatory, then I would rather not be confused by a block of code, then see "ahh, that's what it was supposed to do".

I'd rather know up front...

Answer 6

At least in your example, it certainly requires fewer words to say what you mean. However, for a comment that applies to a block of code, it makes more sense at the top, where it's more likely to be noticed. There is this OCD part of me, though, that wants to do it the the same way every time, so switching it up rankles me a bit.

Answer 7

I'm still in favor of commenting before and sometimes before and after the code block. These two samples one gonna look 'naggy':P

Critical/Important comments enclosing the block.

Sample 1:

// Important: Start CheckForUpdates() on its own thread, since it can take up to a minute to execute
_checkForUpdatesThread = new Thread(new ThreadStart(updateManager.CheckForUpdates));
_checkForUpdatesThread.Start();
// End CheckForUpdates()

Sample 2:

// Important: Please see notes after CheckForUpdates() start
_checkForUpdatesThread = new Thread(new ThreadStart(updateManager.CheckForUpdates));
_checkForUpdatesThread.Start();
// Note: CheckForUpdates() started on its own thread, since it can take up to a minute to execute

Answer 8

If you have to explain what you're doing, why would you explain it after you do it?

Answer 9

Comments above is best.

Stepping aside from code for a moment: When you read a magazine article, it will be broken into sections, each with a heading at the top that summarises the content of the section. This (a) gives you a high-level overview of the article that you can skim-read before you read any of the detailed text, and (b) while reading the article, it informs you that you are moving on to a new topic, and describes what that topic will be.

Code can (and should) be "self documenting", but you shouldn't have to read and understand every line of code to understand how a method works - a summary is usually sufficient. A lot of coding time is spent searching for the chunk of code that we wish to edit. By using a summary comment on each block, I can quickly zero in on the block that is relevant to my task.

In addition, most computer-readable documentation systems (Doc XML, Doxygen, Java doc etc) expect the comment to come before the code it relates to - it's better to remain compatible with that standard.