How do you like your comments? [closed]

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

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 3

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 4

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 5

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 6

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.

Answer 7

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 8

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

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

Commenting code

Answer 9

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