What is the right level of granularity for code commenting?

Question

Commenting in code I believe is very important but recently I've been reviewing code that has left me wondering particular this one.

 //due to lack of confidence with web programming leaving this note in for now

What is the right level of granularity for code commenting?

EDIT: Obviously the above comment is shocking hence why I'm asking the question. I've recently noticed the inline comments in the code at my work place annoying. Instead of getting angry I want discovery the acceptable level of granularity for code commenting in the community.

Answer 1

The comment must be helpful. If it does not explain anything about the source code, it must be removed. It includes comments which repeat what the code does:

// Adding three to the variable n.
this.n = this.n + 3;

or some "false comments" which are in the wrong place:

// 2011-06-22 by Joe: replaced the SQL query by the new one.

Now, how often do we need to put comments? Is it one comment for each ten lines of code? One comment for every forty lines? Well, it depends. Complicated code may have lots of comments. For example it is the case when it is required to write a piece of code optimized for performance more than for readability. Easy to understand code on the other hand may do not have any comment at all (with a few exceptions, like the comments for every method or property or field).

So is //due to lack of confidence with web programming leaving this note in for now comment useful?

Well, it would be if it were more detailed. Reading this comment, we may think that the following code may not match the best practices, or not be very correct, or may even do something different from it was expected to do, unless in some circumstances. But we don't know anything precisely, so we must explore the code to guess (while comments are intended also to avoid forcing the reader to explore the code).

It would be helpful on the other hand to write comments like:

// I'm pretty sure that in web programming, we must keep the following data in
// sessions or in database, but writing specific database queries would be long,
// and I can't find how to use sessions, so I'll keep it this way.

or:

// I'm unsure that the JSON serialization must be done like this. Probably there
// is a method in .NET Framework to do it in one line, but I can't find it.
// TODO: search MSDN for a correct way to serialize to JSON in .NET.

I always suggest adding a TODO in those cases. When you write code, you are expected to know how to write it the correct way. But you may not have time to learn everything you need before writing it. By adding a TODO:

• You notify the reader that you just postponed the search, but are willing to learn new things,
• You can easily find TODO comments later (Visual Studio even shows you a list of TODO automatically from the comments),
• You highlight that the code is not perfect, and must be modified before RTM.

Answer 2

The best commenting approach is to write clear simple code that is extremely obvious in its function and approach and does not need any comments at all.

Personally, I find in-line comments often detract from the ease of understanding a section of code because it breaks up the program logic and adds distractions. For that reason comments should only be used when the program logic itself isn't self-explanatory and you have to add them in order to make the program easier to understand.

Answer 3

I hate those kind of comments, for a few different reasons.

• The code is never going to be as cheap or easy to implement "the right way" as it is right now.
• If external factors are necessitating a sub par solution, that is intended to be fixed later, that should be documented in the bug tracker and, if customer affecting, in the release notes. Not in source code that no one has a compelling reason to revisit.
• If it seems too trivial to track in a bug tracker, it's not worth noting. Either fix it before you check it in or let it go.
• If you don't have confidence in your solution, or flat out don't know how to do it right, go ask. Hoping for someone smarter to happen across that code is not a feasible quality assurance technique.
• If your solution is superior, but for a non-obvious reason, that's the kind of thing to document in the source.

Answer 4

Good code say how things are done.

Good comments say why the code is as it is.

Comments which doesn't say anything about why (or how if the code doesn't - but then the code should be refactored to say so), should be discarded. The one you show is most likely one of these.

Answer 5

I wouldn't have worded it like that but I always comment a section I am unsure about. I often use a few asterisks to make it more visible too, so that I'll notice it while scanning over the code later.

In general, I put a comment at the beginning of every function to describe what that function does, what the parameters are, and what it returns. Then if it's a longish function I'll put comments within the function for every chunk of related code, usually around 5 or so lines. For example, if I have an if/else then I'll usually comment what's going on with each branch.