Deep Simplicity - Rule 5

The next rule we will be looking at in Deep Simplicity is Do not abbreviate. As developers, it is often said - tongue in cheek - that being lazy is a virtue. I think that the laziness of developers is a key source of preventable errors. Copying and and pasting code being the number one offense when it comes to inadvertently adding errors from being lazy. It's even worse for those developers that are reluctant to use an IDE and hack away on vi or emacs. Another way developers are lazy is by shortening the names of classes, methods and variables with abbreviations which lead to confusion and tend to hide larger issues.

I recently came across code that looked like this:

if ($foo->getBwid()) {
    $widget = Widget::getByBarWidgetId($foo->getBwid());
    return $widget;
}

Can any one tell me what a Bwid is? Oh sure you can guess by looking at the context in which it is being used, but are you really sure? look at the amount of energy you'd have to expend just to write this code in the first place. Even if you wrote both the Foo class and the Widget class, I'd bet that you would have to look up the method you wanted to use. If not immediately, a year after you wrote them you'd be screwed. How much more digging would a new developer to the code base have to do?

By looking at the reasons for the abbreviation you can find ways to improve the code. Are you typing the same word repeatedly? You probably should look for duplicated code. Are you doing it because the method names you are using are getting too long? You probably should look for a missing class. Try to keep names to one or two words, this doesn't count for PHP classes that have to bear the weight of namespacing. Zend_Cache_Backend_Memcache is okay, Zend_Cache_Backend_StoreDataOnYourHardDrive is not so great. you should also try to avoid duplicating context. If you have a class named Order, naming a method shipOrder is pointless and sounds weird when you say it out loud: $order->shipOrder(). Naming the method ship(), sounds much better: $order->ship(). Keep things simple and clear and you should be fine. If in doubt, try saying it out loud.

Next is part #6: Keep all entities small.

blogroll

social