Holy crap, is this bizarro world? Programmers are writing TOO many comments? I’ve never heard such a thing! I wish this was in line with my experience.
Just because I am a programmer and I can read code, does not mean I should have to. I’m not a compiler. Sure, I completely, 100% agree that code should be self-documenting where ever possible. On the outskirts of code, you will likely have some type of controlling logic which creates objects and calls functions, all of which should be fairly self-documenting and the flow is obvious and beautiful. These are the trivial cases. But as you get deeper in the meat and potatoes of the code, it becomes harder and harder to understand the code as immediately as the trivial parts. Instead of reading the code like a book, you have to start parsing the code like a compiler. It’s inevitable. Not everything can be broken into a 4-line function with a nice name. In these cases, a simple // XX does YY and then ZZ makes all of the difference in readability. Not only that, but it shows the programmer’s intent. If there happens to be a bug in this area, I can identify what the programmer was trying to do, why her assumptions were wrong, and thus fix the bug. Self-documenting code is completely worthless if it’s inadvertently documenting the wrong thing.
Really, the issue here, is the maintenance phase of the programming life cycle. As we know (From Facts and Fallacies), the maintenance phase consumes 40-80% of the total costs of a project. And maintenance programmers spend 50-60% of their time deciphering the code they are maintaining (Code Complete, referencing another source). So the question is, do comments help this deciphering phase? Yes. They do. They help more than not having them, that’s for sure! I’d rather have too many comments than not enough. I think it’s plainly obvious, but I’m sure there are studies that support it. Here is one with a few seconds of google searching:
Any time you have code that is going to need published documentation, JavaDoc-esque systems do take a lot of space comment-wise, but if you need to maintain documentation anyways, it’s easier to do it right there in the code. It just takes a bit of discipline to remember to update the doc block if necessary whenever you are doing something in the code. Much more convenient than maintaining documentation elsewhere. And it may be useful to other programmers looking at the code, too.
It seems like there are a lot of posts on this blog and associated blogs with the tone of: Generally accepted good thing here is actually TERRIBLE!!! OMG!!!. This is reminiscent of cable news network scare tactics and nonsense to start controversy when there really shouldn’t be any. Yes, using comments, design patterns, regular expressions, XML, etc to the extreme is bad. Of course. This could be said about anything. But what should be known is that they are generally good things, but should be used correctly, with care, and under the appropriate circumstances. Self documenting code and comments are both things a programmer should use and continually attempt to get better at.
Preaching the correct way to use these things is probably going to be much more helpful for those you are trying to address. I see that you aren’t saying all comments are bad- But that is certainly the tone. It’s not until the last sentence that you admit there may be a use for them. I think people like you, Sammy, and others currently on an anti-comment binge are only going to hurt yourselves if you are so strict and unwavering in regards to code commenting.
The effort it takes to write them is vastly (and I mean VASTLY) overstated and the space it takes up on your screen an irrelevancy, as far as I’m concerned (Ignore the dark-green text!). You act like a programmer needs to be a novelist to write simple comments. I think I’ve seen people have a harder time naming functions appropriately.
In short, I don’t think you are young enough to be so idealistic