PhpRiot
News Archive
PhpRiot Newsletter
Your Email Address:

More information

Writing Readable Code

Note: This article was originally published at Planet PHP on 17 April 8140.
Planet PHP

My experience taught me to be verbose and meaningful. I will not talk about code cosmetics. Here are three simple questions. How many times will you write this line of code? How many times will you read that line? How many other people will read it?

The answer to the first question is usually aoonea and the answer to others is aomore than onea. Simple logic tells us that code must be optimized for reading, not writing. Say you just saved 4 characters on a function name. At your typing speed, that's 1 second. A second here and there, and you got yourself 10 minutes.

Now how much time do you spend on average trying to read someone's code to fix a bug? My guess is more than 10 minutes each time. Say the code is really clean and readable, that you can guess what the function does just by its name. You may save yourself anywhere from a few minutes to an hour (or more). Remember that you really spend more time reading code or thinking than actually writing something.

With that knowledge, go for the low-hanging fruit and optimize your code for readability. Here are my top 3.

1. Abbreviations and acronyms don't help. We all know what HTTP and XML is, but the names like t, ci and ctlr don't really strike you as transaction, contact information and controller. Although it allows you to strike less keys, the readability drops considerably and you're losing a lot more time later, because you need to read all the surrounding code to understand the context.

Tip: use full words as much as possible and configure your editor for auto-completion.

2. Ternary operators can create visual clutter. They are useful when code is short and obvious, but can quickly make your code a nightmare to read, especially if you begin nesting conditions. Consider this example:

$shipping = $amount = 40 && $country == "Canada" ? 5.95 : $amount = 50 ? 6.95 : 12.95;

Did you highlight portions of this line to better understand the condition or just didn't bother? That's because it's too hard to read.

Tip: replace complex ternary operators with regular if-statements.

3. Method names must do what they say. Since methods are supposed to do something, I always start with a verb. Is the method getting or setting data? Is it converting? Is it writing a file to disk? Is it extracting pages from a PDF? Is it creating a record in a database? Is it sending a confirmation e-mail?

If you need to explain what the function does after saying its name, then the name might not be meaningful enough. Here are some examples I don't like:

$article-first();

Should I expect an article or a boolean? Does it use id or date to consider an article aofirsta? Maybe it's supposed to bump my article to the front page.

$article-getPath();

The article is in the database, so this will be the path of what? The main image?AThe cached html? Maybe it's the category path Local Sports Hockey.

Instead, I prefer:

$article-isLatest(); $article-getThumbnailPath();

Tip: write method names that can be understood without reading the rest of the code.

Conslusion

I will close my argument with an anecdote from 2008 when I was working for a gaming company. A small game project was outsourced. I was asked to estimate how much time it would take me to make some changes to the code. I haven't seen the code yet. Judging by the usual quality of outsourced projects, I said 4 days. When I got my hands on the code, it only took me 15 minutes. Th

Truncated by Planet PHP, read more at the original (another 899 bytes)