Comment This
I'm sure you've all been told this in the "lurn 2 java" books and the computer science courses taught by high schools or colleges of equivalent quality: You must have to comment your code.
At first blush, this assertion makes perfect sense. You get a bunch of people who don't know jack about programming and need their hands held every step of the way as they look at code, they will agree with the TA's and the book scummers. Their own ignorance is prima facie evidence of the virtue of commenting code.
But then you grow up, you learn that computer languages are arbitrary, you start to think in terms of problem solving rather than detail mongering, and you start to regard comments in code with as much respect as you would the passenger who insists on reading all the billboards out-loud to the other folks in the car.
Yes, I'm saying something that may seem controversial to the newbs and the poor TA's who are forced to look at their incoherently-built code. But to those of us who actually work on solving problems, this is either intuitively or explicitly understood.
Commenting your code is evidence that you suck.
Moreover: Any time somebody begs for you to comment your code, they are admitting that they are too stupid to read actual code and that they are too short-sighted to see the long-term detriment that code comments can pose.
Yeah, you heard me. And I'm not taking it back, either. I meant every word of it. Commenting code is a kind of hazing that professors do just to see how likely you are to put up with inane busywork. Maybe a couple of them want to see if you are capable of articulating what your own code does — perhaps to make sure that you're not just doing the old copy-paste of some code.google.com project … or if you are, you at least you understand what it's doing.
But as you get better at reading code, you'll need comments less and less – just like improvements in your own literacy lead to being able to consume entire sentences without needing a dictionary on-hand. You start to consume entire sentences, knowing their meanings, even if you don't know the precise, annotative definition of each individual word.
Journalists don't interrupt every sentence or even every paragraph with further exlpanations of what they mean. Neither do biology text books (which deal with material that is usually more complex than most programs).
You have to be able to assume a base-line level of competence when you are presenting certain topics. This is true for source code as it is for any other complex aspect of human understanding.
More important than that, when you get better at programming, you know how to express your code in a way that makes its purpose apparent to anybody who knows what they're doing. Chances are real high if your code needs much explaining, it's because you're over-thinking the problem or over-engineering the solution.
As time goes on, you'll end up writing millions of lines of code. You are going to make mistakes in that code and you are going to make mistakes in the comments that you write into code. While a comment can be a great boon for quickening the understanding of that code when it is accurate it can end up being even more of a detriment when that comment is inaccurate than if you never had it.
Consider the following:
// Check to see whether condition BAR is set
if (foo.bar())
{
foo.bas();
}
Somebody reading that comment may take for granted that the bar method is performing some kind of check. This test may be really important like checking for a file lock or attempting to connect to a database. Credulously believing the comment may convince you that you don't need to look at bar()'s actual implementation…
bool FooClass::bar()
{
ruinEverything();
return true;
}
… because at some point in the project, somebody decided that the check was too slow or redundant against a similar procedure in another part of the code. Whatever the case, the comment LIED to you and you ended up needing to dig deeper anyway.
It's the basic tenant of good software quality: Every line of code is a liability. Comments even more so because they are liabilities that the compiler and tests will not catch for you but they can still cost developer time.
Comments, if actively maintained by a good programmer may help an inferior programmer understand what functionality he is ruining when he changes the code but they do nothing to help decent developers nor do they really make bad programmers suck any less.