Every developer has been learned from his teachers how important is to comment his source code. You should comment the classes, the methods, the logic, etc. However nobody explained how exactly to code with comments between the lines. Have you ever seen that
i++; // we increment i with one
That’s a shame! This doesn’t tell you anything, and what will happen if sometime later somebody sits in front of that code? He’d be amazed!
How To
In fact the task is not to determine what are the bad parts of not commenting the code, but how to overcome this. How to write comments. Here are some basic advices.
1. Think about the other developers
First of all the most important thing is to write comments with other programmers in mind. They should understand the logic of your code from your comments and not from the code itself.
2. Write in English
Even you’re not a native English speaker, and you English is not so good, it’s a must to write in English. This is really important when you work for a open source project when always there’s a big community around the project, you cannot be sure that everybody understands your language.
I know that this is difficult – also for me the English is not my native language, but that’s really a must. Once you start doing it, you’ll see that it’s not so difficult.
3. Comment the methods as a black box
Don’t write in a method comment what technique is used to achieve the result. It’s good to describe what the method does, not how it does it.
Bad example:
/**
* returns $a + $b
*/
public function sum($a, $b)
{
return $a + $b;
} |
/**
* returns $a + $b
*/
public function sum($a, $b)
{
return $a + $b;
}
Better:
/**
* Returns the sum of two numbers
*
* @param number $a
* @param number $b
* @returns number $a + $b
*/
public function sum($a, $b)
{
return $a + $b;
} |
/**
* Returns the sum of two numbers
*
* @param number $a
* @param number $b
* @returns number $a + $b
*/
public function sum($a, $b)
{
return $a + $b;
}
4. Comment the logic, not the technical solution
When there’s a loop or a statement it’s useless to describe that this is a loop or statement, isn’t it? A better approach is to describe in a comment why you needed to implement this logic in such way.
Wrong:
...
$arr = array();
$i = 0;
// in a while loop we
// initialize every element with 0
while ($i < 100) {
$arr[$i++] = 0;
}
... |
...
$arr = array();
$i = 0;
// in a while loop we
// initialize every element with 0
while ($i < 100) {
$arr[$i++] = 0;
}
...
Better:
...
$arr = array();
$i = 0;
// we initialize an array of 0s
// to store the sorted elements
// on the first pass... etc, etc.
while ($i < 100) {
$arr[$i++] = 0;
}
... |
...
$arr = array();
$i = 0;
// we initialize an array of 0s
// to store the sorted elements
// on the first pass... etc, etc.
while ($i < 100) {
$arr[$i++] = 0;
}
...
Conclusion
In fact the most important thing is to write comments with other developers in mind. Tell the future developer of that code what’s in the code, and pray for mercy 😉
