We’ve all heard so many times over the years about the readability of code, that some code is more readable than other code, and maybe some code isn’t readable at all. The fact is, all code is readable if you know the language it’s written in. That isn’t just true for programming languages. Consider this sentence:
Colorless green ideas sleep furiously.
It is eminently readable, but it makes no sense. (That was the point Noam Chomsky was making when he constructed the sentence.) This is an extreme case, of course. Most sentences make sense assuming we interpret them correctly. In order to read and understand text, we have to do the following things:
- Build a syntactic representation of the text to figure out its structure and which grammatical role each word is playing,
- Build a semantic representation of the text using the semantic projections of the words in their grammatical roles,
- Use that semantic representation as the basis for reasoning about the text.
Step 1 is easier in programming languages than in general languages because the grammar is more restrictive. However, the other two steps still involve quite a bit of work. In performing those two steps, we are attempting to answer the following questions about source code:
- What is the code doing?
- Why is the code doing that?
I refer to this process as cognitive effort, and it is what separates comprehensible code from code that is not so comprehensible. Code that is easily understandable is referred to as having a low cognitive effort demand (CED), and code that is hard to understand is referred to as having a high cognitive effort demand. (The sentence near the beginning of this post could be said to have an infinite CED because it is nonsensical.)
How can we lower the cognitive effort demand? Better naming is the obvious first choice. By choosing variable names that represent the values they contain, method names that indicate what the code inside the methods does, and class names that describe the purpose and role of the classes within the software, we can make code much easier to understand. Occasionally, I’ll do a simple code kata and, after it’s completed, make several subsequent passes over the code, updating and improving the names in the code during each pass. It’s a good exercise and I recommend it.
Another way to reduce the cognitive effort demand is to use effective abstractions. An effective abstraction ties a unit of code to a concept that is well understood by many people. An example of this can be found here. The LogEventRecorder records events of some sort and plays them back. The abstraction I chose is that of a digital recorder (or tape recorder if you’re as old as I am). Digital recorders have buttons that let you record, play, pause, stop, fast forward and rewind recordings. Thus, the LogEventRecorder has methods with those names. This abstraction reduces the cognitive effort demand because with only a cursory reading, you see the methods that correspond to the buttons on the digital recorder. This makes it easy to figure out what the code in each method is doing (implementing one of the features of a digital recorder) and why it’s doing that (so we can record and play back a log of events). Building code in this way is easier said than done, of course. Many code units don’t easily correspond to well-known abstractions. But when one does, take advantage of the opportunity.
When you write a code unit corresponding to an abstraction, consider whether it “completes the abstraction”, in other words, supports all of the operations normally associated with the abstraction, and name it accordingly. LogEventRecorder completes the digital recorder abstraction, or at least comes pretty close to it. But what if I decided that LogEventRecorder shouldn’t support fast forward and I removed that method? Would LogEventRecorder still be a good name? Maybe, but then a fellow developer might look at the code and wonder why there’s no fast forward method since we’re using the digital recorder abstraction, and she may even consider whether such a method should be added. If so, then I will have increased the cognitive effort demand. I should change the name of the class to reflect the fact that while it’s a recorder, it intentionally doesn’t support fast forward. I’ll leave the determination of a better name as an exercise for the reader (since I can’t think of anything good).
When you write code, keep in mind how much cognitive effort you are demanding of the reader of that code, and how you can lower the cognitive effort demand through good naming and the use of effective abstractions.