What is your personal approach/take on commenting?

Question

Duplicate

What are your hard rules about commenting?

A Developer I work with had some things to say about commenting that were interesting to me (see below). What is your personal approach/take on commenting?

"I don't add comments to code unless its a simple heading or there's a
platform-bug or a necessary work-around that isn't obvious. Code can change and comments may become misleading. Code should be
self-documenting in its use of descriptive names and its logical
organization - and its solutions should be the cleanest/simplest way
to perform a given task. If a programmer can't tell what a program
does by only reading the code, then he's not ready to alter it.
Commenting tends to be a crutch for writing something complex or
non-obvious - my goal is to always write clean and simple code."

"I think there a few camps when it comes to commenting, the enterprisey-type who think they're writing an API and some grand code-library that will be used for generations to come, the craftsman-like programmer that thinks code says what it does clearer than a comment could, and novices that write verbose/unclear code so as to need to leave notes to themselves as to why they did something."

Answer 1

the purpose of comments is to explain the context - the reason for the code; this, the programmer cannot know from mere code inspection. For example:

strangeSingleton.MoveLeft(1.06);
badlyNamedGroup.Ignite();

who knows what the heck this is for? but with a simple comment, all is revealed:

//when under attack, sidestep and retaliate with rocket bundles
strangeSingleton.MoveLeft(1.06);
badlyNamedGroup.Ignite();

seriously, comments are for the why, not the how, unless the how is unintuitive.

Answer 2

I agree with the self-documenting code theory, if I can't tell what a peice of code is doing simply by reading it then it probably needs refactoring, however there are some exceptions to this, I'll add a comment if:

• I'm doing something that you don't normally see
• There are major side effects or implementation details that aren't obvious, or won't be next year
• I need to remember to implement something although I prefer an exception in these cases.
• If I'm forced to go do something else and I'm having good ideas, or a difficult time with the code, then I'll add sufficient comments to tmporarily preserve my mental state

Answer 3

Here's how I wrote code:

if (hotel.isFull()) {
    print("We're fully booked");
} else {
    Guest guest = promptGuest();
    hotel.checkIn(guest);
}

here's a few comments that I might write for that code:

// if hotel is full, refuse checkin, otherwise 
// prompt the user for the guest info, and check in the guest.

If your code reads like a prose, there is no sense in writing comments that simply repeats what the code reads since the mental processing needed for reading the code and the comments would be almost equal; and if you read the comments first, you will still need to read the code as well.

On the other hand, there are situations where it is impossible or extremely difficult to make the code looks like a prose; that's where comment could patch in.

Answer 4

I very very rarely comment. MY theory is if you have to comment it's because you're not doing things the best way possible. Like a "work around" is the only thing I would comment. Because they often don't make sense but there is a reason you are doing it so you need to explain.

Comments are a symptom of sub-par code IMO. I'm a firm believer in self documenting code. Most of my work can be easily translated, even by a layman, because of descriptive variable names, simple form, and accurate and many methods (IOW not having methods that do 5 different things).

Answer 5

I write comments that describe the purpose of a function or method and the results it returns in adequate detail. I don't write many inline code comments because I believe my function and variable naming to be adequate to understand what is going on.

I develop on a lot of legacy PHP systems that are absolutely terribly written. I wish the original developer would have left some type of comments in the code to describe what was going on in those systems. If you're going to write indecipherable or bad code that someone else will read eventually, you should comment it.

Also, if I am doing something a particular way that doesn't look right at first glance, but I know it is because the code in question is a workaround for a platform or something like that, then I'll comment with a WARNING comment.

Answer 6

We add comments which provide the API reference documentation for all public classes / methods / properties / etc... This is well worth the effort because XML Documentation in C# has the nice effect of providing IntelliSense to users of these public APIs. .NET 4.0's code contracts will enable us to improve further on this practice.

As a general rule, we do not document internal implementations as we write code unless we are doing something non-obvious. The theory is that while we are writing new implementations, things are changing and comments are more likely than not to be wrong when the dust settles.

When we go back in to work on an existing piece of code, we add comments when we realize that it's taking some thought to figure out what in the heck is going on. This way, we wind up with comments where they are more likely to be correct (because the code is more stable) and where they are more likely to be useful (if I'm coming back to a piece of code today, it seems more likely that I might come back to it again tomorrow).