Rob Cook

Home | Donate



Of all the properties that make for good code, I would argue that readability is the first amongst them. It doesn't matter how clever or elegant the code is, if it cannot be readily comprehended by another developer then it is of little use. (Developer in this sense is one who is fully comfortable with the syntax of the target language. Code may be highly readable, yet obscure to those unfamiliar with the language.)

Readability is also one of those properties that can be highly subjective. Some may prefer concise use of available language constructs, others a more verbose simplicity of minimal features. This can make it hard to enforce readability at the time of a code review. That said, it is important that this property is imbued within your code base to avoid it becoming unmaintainable legacy.

A rule of thumb I use is to make the code read like broken English. (This is often as good as it gets with a programming language anyway, given the somewhat stilted nature of keywords that must be used.) To this end, it becomes of paramount importance to name things well. Variables, methods, classes, and interfaces - all should be thought about and picked with care.

Try out several possibilities by writing out the calling code. Settle on one that is the most expressive of the code's intent. Of course the famous adage has it that there are only two things that are truly difficult in programming, and naming things is one of them!

One can also devote time to reading to enhance their vocabulary. Just as authors of books will read voraciously, we as authors of code must read at least regularly to stay sharp in this regard. The more words at your disposal, the more choice you have in naming things, and the higher the chance you can pick just the right terminology for the case at hand.

We are lucky as programmers in that we can assign a name to pretty much any piece of code or statement. We are (within the rules of naming imposed by the target language) free to pick any label we wish to apply. That flexibility also comes with the responsibility to chose wisely. No one is stopping you from using single letter variables or cryptic method names!

For a team environment, I suggest at least attempting to agree on a set of guidelines (and I say guidelines, rather than rules) for readability. These can help inform the struggling programmer lost in a sea of words. They can also keep the code reviewer in check when making suggestions for changes.