When to comment code
If you are a developer, you don't speak one language, you speak at least two. If you already speak several spoken languages, like French, English, Spanish, Russian, or Canadian, then you add to it "programming".
What I'm saying is that you don't need to comment all of your code. Big concepts perhaps, variable names and describe the use for a function. But not everything little thing. You don't have to tell me
if ( $a == $b ) // does $a equal $b? { // echo the positive response echo "Certainly, $a IS equal to $b!"; } else { // $a is not equal to $b, so output a response // to tell the user that it was not the case. echo "Sadly, $a is not equal to $b. Wasn't that obvious?"; }
When you read code, you understand without even thinking what it says. You scan down. If it's a hard sentence, like something from Shakespeare or The King James Version or Beowulf, then you re-read it a few times, maybe copy it to a script and try it out a bit. Commenting code like above interrupts me.
If I don't understand a word in a book, I can figure it out by context or find a dictionary or iPhone app. I can even google the word. That's pretty similar to code in this context. I'm just saying: there are ways to figure it out. Your "reader" isn't stupid. If he doesn't know what that if statement means, you're comment isn't helping him.
Don't tell me comments help people who don't understand code learn to understand it. Documentation does that. Tutorials do that. Comments aren't teachers.
Having said that, it's certainly easier to read a commented function or object that will tell you what it does, what it returns and what it expects you to pass it. That's a shortcut so I don't have to read the whole function. It's the Cliff Notes edition. Think of it that way. If you are commenting an if statement or while loop, you need to refactor your code, not comment it. Maybe it's some rule in Programming 101, "comment only at the beginning of files and outside functions." Having never taken a class in Programming (gasp!) I wouldn't know. It should be said like that, though.
Would you write a paragraph like this:
Comments shouldn't say the same thing as the code (// $comments != $code). If it does, it should be removed (// if ( $comment == $code ) { unset($comment) }. It's just interrupting ( // break; ) the reader ( // private $reader; ) who speaks geek.
Next time you add a comment to your code, figure out if it would really help the next dev who comes along. If it says what the code already says, it will not. If it has to explain complex code, perhaps you'd be better off refactoring to a simpler way? If it explains what a function does, yeah, that's probably helpful. Like in they way that some books start each chapter saying, "in this chapter you'll learn these 7 things" and go on to list them.
I'm no expert. I'm probably not even a very good programmer. I call myself a developer to avoid that distinction. I'm writing this because I see a lot of useless comments. But I have a confession to make. I comment like this (and these are VERY useful comments) from time to time. But the reason is: I'm lazy. If I took the time to refactor the code and write tests, I wouldn't have to rely on the "Actung!" comments.
// SIC! Don't change it will break - it is misspelled all over the place; ACHTUNG!; $varable = false;
I should instead go and fix (varable to variable) it wherever, but I commented instead.
