Comments are always wrong -- right, or no? [closed]

Question

Randomly ran across this blog on how one should never read comments, and thought to myself all the comments I've read that were either wrong, dated, or simply confusing. Should one simple never read comments and/or just use regex replace pattern to delete... :-) ...just kidding, but really, maybe not. At the very least seems like comments and the related code should be have timestamps. Agree, or no?

FYI, blog appears to be by this stackoverflow user: Nosredna

Answer 1

An inaccurate comment is just as serious of a bug as wrong code. If it is a persistent problem, I would say the project has serious issues. Big projects such as PostgreSQL (94M uncompressed in src directory) rely on accurate comments to help programmers understand things quickly. They also take comments very seriously.

edit:

Also, if you can not summarize what your function is doing, then who can? After you are done writing a function, writing the comment for it can be a test that you fully understand what is going on. If things are still a little muddy in your mind, it will become very apparent when you try write the comment. And this a good thing, that shows what still needs to be worked on.

Answer 2

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.