Donate to protect them directly or help international organizations.
Writing Readable Code
December 14th, 2012
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 "one" and the answer to others is "more than one". 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 "first"? 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? The 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.
Conclusion
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. The project manager asked me how come I estimated so high. I explained that the code, unlike anything I saw before, was of high quality and written in a very readable and easy to understand manner. And that's just a tiny drawing and stamping game for kids, with only a few hundred lines of code. Imagine how much time you can save on a complex project that has a million lines of code.
These are but a few examples. There are many more posts online on the subjet and I suggest you explore them as well:
http://blog.ashodnakashian.com/2011/03/code-readability/
Previous: Performance & Scalability Are Different Things Next: Conference Organizer Tip #1: Advisors