Software design and readability

Software development is mostly about knowledge building – finding out what customers need, what ideas work and what don’t (Lean Software Development). This knowledge is stored in multiple ways inside an organization. Much of it will be in the heads of the people involved but the single source of truth is the code itself. Hence the ability to store knowledge (especially in the long term) depends on how well we are able to put this knowledge into the code.

Of course there is very little value in any text that is full of wisdom but written in such style that makes it very difficult to comprehend. Hence I believe the best measure for code (or software design in general) is its readability.

What makes writing readable code hard is that the value of readability of particular piece of code is not so apparent at the time of writing it. All the logic – the business rules and concepts are fresh in the mind of the developer. He may not even notice that he has hidden actual intent behind layers of technical implementation and constraints.

What are the ways to improve readability? Essentially better readability means that it takes less time to understand the purpose of given piece of code. Like in order to understand what are the main topics covered in a book we don’t need to read it from cover to cover but instead can just check the table of contents. In software systems this “table of contents” is formed by names of subsystems, modules, methods and even local variables. If these are well composed and have good (intent revealing) names then they make finding the places that need to be changed faster. For example package names like com.mycompany.domain, com.mycompany.service, com.mycompany.repository are likely not going to help us find something fast as opposed to names like com.mycompany.user, com.mycompany.customer, com.mycompany.recipient are going to be much more informative.

One of the primary principles behind design patterns is separation of pieces that are influenced by different forces. From the perspective of readability this means making it easier to filter out the effects of some specific change. For example following Single Responsibility Principle helps to build more meaningful table of contents. According to SRP every piece of code is required to deal with one single thing which makes finding good names a lot easier. Similarly using names of common design patterns or using ubiquitous language are both good ways of packing more meaning into less words. For example OrderBuilder tells more about how Orders can be created than OrderGenerator or in e-mail application AddressBookService tells more than ListItemService.

So code is the medium for storing knowledge and knowledge is useful only if it is easy to understand.