7 tips to write intelligible code
27 July 2008
1 comment
Writing intelligible code helps to increase the productivity of a developing team, even if you are an independent worker. Why is it so important to write intelligible code? How can it improve the productivity of my team? A messed up code could delay your partners understanding, or it could create a barrier for new developers. Even trying to understand your own code could be a real challenge as well. Here are 7 tips of how to make more intelligible PHP code (coding style tips):
- 75-85 characters per line: Each line must contains approximately 75-85 characters. If a line exceeds more than 85 characters, consider splitting the line into multiple lines. It will be helpful for code readability. You can see a great post on this topic in Paul Jones’ blog. He talks about why this limitation is not really arbitrary, and he puts some brilliant examples such as this one:
Bad
list($foo, $bar, $baz) = array(Zim::getVal('foo'), Dib::getVal('bar'), Gir::getVal('baz', Gir::DOOM));Good
$foo = Zim::getVal('foo'); $bar = Dib::getVal('bar'); $baz = Gir::getVal('baz', Gir::DOOM); - Assignment statements: Assignment statements ought be aligned for better readability. Let’s see an example:
Bad
$example = 'string_value'; $anotherExample = 42; $exampleInst = new ExampleClass();Good
$example = 'string_value'; $anotherExample = 42; $exampleInst = new ExampleClass(); - 4-spaces block indentation: Use an indent of 4 spaces with no tabs. It helps to avoid problems with diffs, patches and SVN history. It helps the readability as well. Usually tabs are 8 spaces length, which means a 5th-block indent starts 40 spaces from the left border (nearly to 50% of a code line).
{block1} {block2} {block3} ... -
Control & conditional structures: These statements must have one space between the control keyword (if, else, for, while, …) and the opening parenthesis, to distinguish them from function calls (which obviously don’t have a space). It’s nice to always use curly braces because they help to decreases the likelihood of logic errors.
if ($display === 1) { while ($obj->next()) { echo $obj->toString(); } } -
Class and function/methods declarations: Class and function/methods declarations have their opening brace on a new line.
class Foo { private $_obj; public function __construct($obj) { $this->_obj = $obj; } } - Comma-space between items of a list: When we list some items, it’s nice to separate them clearly with a comma followed by a space.
BAD
$example = array(Foo::get('key',2),$value,true);GOOD
$example = array(Foo::get('key', 2), $value, true); - Use constants properly: If we have a method which returns some status codes, it’s nice to use literal constants. Having descriptive constants helps to make better intelligible code. For example:
BAD
class Foo { public static function getStatus() { $res = 0; if (!self::isValid()) { $res = 1; } ... if ($res === 0 && self::isRepeated()) { $res = 2; } return $res; } }GOOD
class Foo { const STATUS_SUCCESS = 0; const STATUS_FAILURE = 1; const STATUS_REPEATED = 2; public static function getStatus() { $res = self::STATUS_SUCCESS; if (!self::isValid()) { $res = self::STATUS_FAILURE; } ... if ($res === self::STATUS_SUCCESS && self::isRepeated()) { $res = self::STATUS_REPEATED; } return $res; } }
These tips are just some coding style tips. If we really want to write intelligible code, we would keep in mind many more things like to use software patterns, to make use of well established software practises, …
The insistence of running Adobe Photoshop on GNU/Linux is a good example of this. I’m not going to talk about the Photoshop/The Gimp challenge, although I manage well myself using The Gimp. Each user should know that Adobe Photoshop has a horrible license which it doesn’t allow the freedom to run, modify and redistribute it. The Gimp (GNU Image Manipulation Program) is available under the terms of the GNU General Public License (GPL), so we have the freedom to run, copy, change, study, distribute, improve the software and release our improvements. That’s how the community gets benefits. The Gimp, like free software, contributes to human knowledge, whilst Adobe Photoshop, like non-free software does not.
