How do you like your comments?

Question

What are your best practices for comments? When should they be used, and what they should contain? Or are comments even needed?

Answer 1

Comments are essential for maintainability. The most important point to remember is to explain WHY you are doing something, not WHAT you are doing.

Answer 2

I think it depends on the scenario.

Methods/functions/classes need a short description of what they do, how they do it, what they take and what they return, if not immediately obvious and that usually (in my code) comes in the form of a javadoc-style comment block.

In-block code, I tend to leave a comment above a block of lines to explain what it does, or one at the end of line if it's a short and cryptic function-call.

Answer 3

In school, the rule was to comment everything, so much so that comments outweigh code. I think that's silly.

I think comments should be used to document the "why" behind code, not the "how"... the code itself explains the "how". If there's an operation that isn't really clear as to why it is done, that's a good place for a comment.

TODO's and FIXME's sometimes go in comments, but ideally they should go in your source code management and bug tracking tools.

The one exception of where I don't mind seemingly useless comments is for documentation generators, that will only print documentation for functions that are commented - in that case, every public class and API interface needs to be commented at least enough to get the documentation generated.

Answer 4

Use the tag search and you'll find SO has a heap of discussion about code comments already:

http://stackoverflow.com/questions/tagged/comments

http://stackoverflow.com/questions/36432/commenting-code

Answer 5

First of all, I come from the context-based camp, which states that there are no best practices, just good practices dependent on context. Those contexts may include the language you're using, the kind of software you're coding (is it life-critical, is it a shopping cart, what?), and your personal style and preference.

Of course the pat but true answer (again, dependent on language, circumstances, etc.) is that code should be as self-documenting as possible. I cannot overstate the importance of having meaningful class and variable names. I can intuit my way through code I've never seen before if I can easily puzzle out what it's doing. Well-written code does this.

That said, don't hesitate to insert a comment anywhere that helps you or will help explain a possibly hard-to-read bit of code. Compilers ignore them, so there's virtually no expense to them.

Answer 6

Ideally your program can communicate with the reader in code and not in comments. The ability to write software that other programmers can quickly understand separates the best programmers from the average in my opinion. Typically, if you or your colleagues cannot understand a section of code without comments, than this is a "code smell" and refactoring should be in order. However, there will some archaic libraries or other integration that a few comments to guide the average developer is not necessarily bad.

Answer 7

As often the answer is: it depends. I think the reason you wrote a comment is very important for the decision, if the comment is good or bad. There are multiple possible reasons for comments:

• to make the structure clearer (i.e. which loop ended here)

Bad: This looks like a possible code smell. Why is the code so complicated, that it needs a comment to clear that up?

• to explain, what the code does

Very bad: This is in my opinion dangerous. Often it will happen, that you later change the code and forget about the comment. Now the comment is wrong. This is very bad.

• to indicate a workaround/a bugfix

Good: Sometimes a solution to a problem seems clear, but the simple approach has a problem. If you fix the problem, it may be helpful to add a comment, why this approach was chosen. Otherwise another programmer later can think, that he 'optimize' the code and reintroduce the bug. Think about the Debian OpenSSL-problem. The Debian-developers removed an unitialized variable. Normally an unitialized variable is a problem, in this case it was needed for randomness. A code comment would have helped to clear that up.

• for documentation-purposes

Good: Some documentation can be generated from special formatted comments (i.e. Javadoc). It is helpful to document public APIs, that is a must-have. Important is to remember, that documentation contains the intention of the code, not the implementation. So answers the comment the question 'Why you need the method (and how do you use it)' or What does the method?

Answer 8

Aside from normal commenting, I usually leave little easter eggs for other developers to find.

Answer 9

I think the new movement to remove comments is bad... the reason, there are a lot of programmers that think they are writing easy to understand code that does not need comments. But in reality its just not the case.

What percentage of other peoples code do you read and instantly understand it.. Maybe I read too much classic asp, Perl and C++ but most stuff I read is tricky to skim.

Have you ever read someone's code, and became completely confused by it. Do you think they thought while they are writing, this is crap but I don't really care. They probably thought ohh... this is very clever and it will be SUPER fast.

Answer 10

Have a look at Code Complete. Its simply best for such topics.

Answer 11

Just some remarks:

Comments are important for everything that can not be easily inferred from the code (e.g. complex mathematical algorithms).

The problems with comments is, that they need to be maintained like the code but often are not maintained at all.

I don't like comments like this:

// Create the "Analyze" button
Button analyzeButton = new Button();
analyzeButton.Text = "Analyze";
analyzeButton.Location = new Point( 100, 100 );
Controls.Add( analyzeButton );

Better:

CreateAnalyzeButton();


void CreateAnalyzeButton()
{
    Button analyzeButton = new Button();
    analyzeButton.Text = "Analyze";
    analyzeButton.Location = new Point( 100, 100 );
    Controls.Add( analyzeButton );
}

Now the code tells the whole story. No need for a comment.