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;
}

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;
}

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; 
}
...

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; 
}
...

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

After reading one of the latest posts from Stoyan Stefanov’s blog – phpied.com I stumbled upon an interesting construction in JavaScript describing how to check an object property existence. I’m going to cover this case using as an example the console object, which comes with the Firebug enabled, and I think it may be very useful, just because this object is widely used, but doesn’t exists over all the browsers, even under Firefox when Firebug is disabled. This construction is known as the IN statement and it looks something like that:

property in object

which I’m going to cover later in details.

How you detect a variable existence?

There are three main ways to detect the existence of a property I see in my practice.

1. The most widely used:

if ( console ) { ... }

2. The second and more professional one:

if ( typeof console != 'undefined' ) { ... }

3. And finally the third and most unknown:

if ( console in window ) { ... }

Of course two of them are wrong! Which one should be changed?

Is everything working correctly? No!

Lets see how they are working. First of all I’m going to test all of them on Firefox 3.6 either with enabled and disabled Firebug, just shouting with old school’s alert().

Now the first one using the IN statement:

if ( console in window )
   alert('object exists!');
else
   alert('object doesn\'t exists!');

With Firebug disabled the answer is … nothing! No alert! That’s because the syntax is wrong. There’s an error within the IF statement. We should modify a bit the first row like that:

if ( 'console' in window )
   alert('object exists!');
else
   alert('object doesn\'t exists!');

Now everything’s OK. With a disabled Firebug the answer is: “object doesn’t exists!”, and after enabling it, normally the “object exists!”.

Lets move on the next example:

if ( console )
   alert('object exists!');
else
   alert('object doesn\'t exists!');

With Firebug enabled the answer is as we expect: “object exists!”, but after disabling it yet again – nothing?! Why’s that? Because the console object doesn’t exists anymore and the IF statement doesn’t return true or false, but simply crashes. How to modify the code? Simply by adding a window.console instead of console.

if ( window.console )
   alert('object exists!');
else
   alert('object doesn\'t exists!');

Than the answer is: “the object doesn’t exists!” after what we expected!

The third method is the mostly used, just because it’s completely clear what’s the goal of the IF statement:

if ( typeof console != 'undefined' )
   alert('object exists!');
else
   alert('object doesn\'t exists!');

In both disabled and enabled Firebug the answer is as expected!

Now the IN statement may be used if not for the console, but for checking the existence of a property of within an object.