Understanding Code

Every programmer should be able to understand and reason about a line of code in one of his* working languages. It’s far more useful, though, to be able to understand and reason about blocks of code.

This is one of the main purposes of coding standards, particularly formatting rules: to make code easy to read and understand. The shape of the code on the screen should tell you something about how it works before you read a single word of it.

However, reasoning about individual lines of code is too slow a process when you want to know about how a large piece of software works. Imagine living your life without ever seeing or hearing about cars, and then being presented with one. If you had to understand what it did, but now necessarily how it did it, would you prefer to take the car apart and examine every component, or to experiment with the controls? Wouldn’t it be easier still if the car’s controls had labels on them that described what they did?

What the poor maintenance programmer needs to be able to do is think in terms of large blocks of code. Two things wil help him to do this: orthogonality and sensible naming.

In programming terms, orthogonality means that each named block does what it is supposed to do and no more. (If it did any less, that would be a bug). When you use the gear stick, it doesn’t change the gear and apply the brakes. When you use the steering wheel, it doesn’t steer the car and turn on the CD player. In these examples, the controls for the gear, brakes and steering are unhelpful because they are not orthogonal – conceptually different parts of the system cannot be used in isolation from each other.

Sensible naming is almost as simple as it sounds. Functions should generally be named for what they return, and procedures for what they do. This helps with readability of code calling these blocks. The important thing to remember about naming, though, is to take a step back when doing it. The names that are obvious to you when you’ve just spent two days coding something will not be obvious to anyone else, and in 18 months they won’t be obvious to you either. As far as possible, your code should be readable to someone who is not closely acquainted with the subject matter.

*You can say it’s sexist, but we all know it’s actually quite realistic.

3 thoughts on “Understanding Code

  1. Some of the Domain Driven Design ideas of ubiquitous language help in that the code should follow the language of the domain.

    So SteeringWheel.turnLeft and SteeringWheel.turnRight for example which matches the procedure rule you have here.

    However some chained functions (such as the Builder pattern) cannot follow the return type name convention.


    I think that’s readable but withKey has to return Ignition.

  2. Before I get my software design license revoked I should say that SteeringWheel.turnLeft/Right is just what a steering wheel physically does. In a domain or context sense the methods should be:


Leave a Reply

Your email address will not be published. Required fields are marked *

I accept that my given data and my IP address is sent to a server in the USA only for the purpose of spam prevention through the Akismet program.More information on Akismet and GDPR.

This site uses Akismet to reduce spam. Learn how your comment data is processed.