Comments are always wrong — right, or no?

Personally I don't write a whole lot of comments, but common types of comments I do write are:

• (sketch) proofs that my code is correct
• explanations why not to just do the obvious thing (e.g: optimization was required, the API I'm calling is shockingly misleading, the "obvious thing" led to a subtle bug)
• a description of the input edge-case which necessitates special handling, thus explaining why the special handling code appears
• a reference to the requirement or specification which mandates the behaviour implemented by a particular line of code
• top-level description of a series of steps taken: ("first get the input", "now strip the wrapper", "finally parse it"), which aren't needed if the names of the functions called for each step are well-chosen and unambiguous in context, but I'm not going to write a do-nothing wrapper for a generic function just to give it a more specific name for one single use
• documentation to be extracted automatically. This is a large proportion of comments by volume, but I'm not sure it "really counts".
• things that could be part of the documented interface, but aren't because they might need to change in future, or because they're internal helper stuff that outsiders don't need. Hence, useful for the implementer to be aware of, but not for the user. Private class invariants are included in this - do you really want to read through the whole class every time you want to rely on "this member is non-null", or "size is no greater than capacity", or "access to this member must be synchronized"? Better to check the description of the member before assigning to it, to see whether you're allowed to. If someone doesn't have the discipline to avoid breaking a clearly commented invariant, well, no wonder all their comments are wrong...

Some of those things are handled by comprehensive tests, in the sense that if the tests pass then the code is correct (hah), if you have the test code open too then you can see the special input cases, and if some fool hides the comments, makes the same mistake I originally did, and refactors my code to do the obvious thing, then the tests will fail. That doesn't mean comments don't handle it better, in the context of reading through code. In none of these cases is reading the comment a substitute for reading the code, they're designed to highlight what's important but not obvious.

Of course in the case of auto-docs, it's perfectly reasonable, and probably more usable, to view the documentation separately.

When debugging, as opposed to making changes, it's way more valuable to let the code explain itself. Comments are less useful, especially those private invariants, because if you're debugging then there's a reasonable chance that whoever wrote the code+comments made a mistake, so the comments may well be wrong. On the plus side, if you see a comment that doesn't reflect what the code does, there's a reasonable chance you've found a bug. If you just see what the code does, it might be some time before you realise that what the code does isn't what it's supposed to do.

Sometimes good naming goes a long way towards replacing comments. However, names can be just as misleading as comments if they're wrong. And, let's be honest, frequently names are at least slightly misleading or ambiguous. I doubt that the author of that blog post would go to the extent of replacing all names with "var1, var2, func1, func2, class1, class2 ...", just to make sure that they weren't distracted by the original author's incorrect intentions for the code. And I don't think it's any truer to say that "comments are always wrong" than to say that "variable names are always wrong". They're written by the same person at the same time with the same purpose.

Comment why you are doing something and not what you did syntactically.

In the real world, programming does not just mean writing code. It means writing code that another programmer (or yourself, in 3 months time) can understand and maintain efficiently.

Any programmer who tells you that comments/documentation are not worth the time it takes to write/maintain them has a number of problems:

• His long term work rate (and that of any colleagues who have to work with his code) will be lower than it could be. People will waste a lot of time understanding code that could be described in a quick sentence.

• Bug rates relating to his code will be higher than they could be, because all those assumptions and special cases that he forgot to mention will constantly trip people up. (How many times have you had to do something "unusual" in your code to make something work, forgotten to comment it to say why you did it that way, and then later on thought it looked like a bug and "fixed" it, only to find that you've broken things horribly because of a subtlety you didn't remember?)

• If he is too lazy to write down how his code works or should be used, what other shortcuts is he taking? Does he bother to check for nulls and handle exceptions? Does he care about his interfaces being consistent? Will he bother to refactor the name of a method/variable if its underlying meaning changes? Usually bad commenting is just the tip of the iceberg.

• Many such programmers are too focussed on "the cool stuff" (like optimising every last cycle out of their code, or finding a clever way to obfuscate a seemingly simple piece of code into a mindboggling template) to understand commercial realities (e.g. he may have trouble getting his code working and shipped to deadlines because he focusses on squeezing unnecessary performance out of it rather than just getting the job done)

• How good are his designs? I do most of my design and thinking when I write down docs/comments. By trying to explain things to the reader of my comments, I flush out a lot of flaws and assumptions that I otherwise would miss. I would go so far as to say that I usually write comments (my intent/design) and then sync the code with them. In most cases if there is a bug in my code, it is the code that is wrong not the comment.

• He has not realised that by using good variable naming, well designed naming prefixes/conventions, and documentation comments, he can make much better use of fabulous time-saving features of his IDE (auto-complete, intellisense help, etc), and code much faster, with lower defect rates.

Fundamentally, he probably doesn't understand how to write good comments:

1) Comments should act as a quick-read summary of a chunk of code. I can read one brief line of text instead of having to work out the meaning of many lines of code. If you find yourself reading the code to navigate it, it is poorly commented. I read the comments to navigate and understand the code, and I only read the code itself when I actually need to work on that specific bit of it.

2) Method/Class comments should describe to a caller everything they need to know to use that class, without having to look inside the "black box" of the code implementation. They will be able to quickly grasp how to use the class/method, and understand all the side effects and the "contract" that an API provides - what can be null and what must be supplied, and which exceptions will be thrown, etc. If you have to read the code to get this, it's either badly encapsulated or badly documented.

3) Use tools like my AtomineerUtils addin or Submain's GhostDoc, which mean that his documentation comments can be kept in sync with the code with very little effort.

Code comments can sometimes be invaluable. Many times I've struggled to determine the intent of code unsuccessfully. For code of any complexity, it can be helpful if the author documents their intent. Of course, well written unit tests can make intent clear as well.

Some comments are useful and good, other comments are not.

Yes, comments and code should be timestamped, but you shouldn't timestamp it yourself. Your source control system should manage this for you, and you should be able to access this information (e.g. using cvs annotate or svn blame).