Tag Archives: Software engineering

Four Things to Know when Writing Comments

web development, , , , , , , , , , ,

How to write comments
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;
}

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 😉

Build a List Tree with the Beauty of jQuery

javascript, micro tutorial, , , ,

This is nothing useful, but let me show the beauty of jQuery. This snippet just adds more and more nodes on a simple UL based tree.

Here’s the HTML:

<ul>
    <li><a href="#">Node 1</a></li>
    <li><a href="#">Node 2</a></li>
    <li><a href="#">Node 3</a></li>
    <li><a href="#">Node 4</a></li>
</ul>

And that’s the jQuery:

var index = 5;
$('li > a').live('click', function() {
    $(this).parent().append('<ul><li><a href="#">Node ' + index + '</a></li></ul>');
 
    index++;
 
    return false;
});

And here’s the demo.

JSON and Zend Framework? – Zend_Json

micro tutorial, PHP, zend framework, , , , , , , , , , , ,

That’s really a good Zend Framework’s class that help you do the encode/decode job very easily. First of all it escapes everything for you and second it prints a correct/valid code. Note that sometimes if you have a trailing whitespace after the closing PHP tag – ?> that will result in an error.

Here’s some code:

public function jsonAction()
{
	$data = array(3,4,'test', 'my-name' => 3,4);
 
	echo Zend_Json::encode($data);
 
	$this->_helper->viewRenderer->setNoRender(true);
	$this->view->layout()->disableLayout();
}

and the result is:

{"0":3,"1":4,"2":"test","my-name":3,"3":4}

Note that all integers are printed without double quotes – which saves some space!

Detecting Pressed Key with e.which in JavaScript

javascript, , , , , , ,

You have definitely decided to get which key has been pressed with JavaScript? This is very common when it comes to an Enter key press over a form element. Actually this should be automatically done by the browser, but when it comes to a default prevented form you’ve to check it for yourself.

The job can be done with a event’s which check. Let me show you some JavaScript/jQuery code:

$('.selector').click(function(e) {
	console.log(e.which);	
});

Note that this can be checked under Firefox and/or Safari like browsers which support the console object. This will give you the idea which key is pressed in a number value. The Enter is usually 13!
If you don’t have such browser, you can replace that code with something like:

$('.selector').click(function(e) {
	alert(e.which);	
});

PHP: Conditionals Coding Style

PHP, , , , , , , ,

Just to continue with PHP coding style, let me suggest a conditional statement coding standard. Just don’t use large three operands conditions like that:

condition ? if_true : if_false

If it’s too long it will be difficult to read and maintain. Better is:

(condition)
	? (if_true)
	: (if_false);