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

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

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 4

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 5

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 6

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