Software Design and Readability
Software development is mostly about knowledge building – finding out what customers need, what ideas work and what don’t. An organization stores this knowledge in multiple ways. Naturally much of this knowledge is in the heads of the people who build the product. However, the single source of truth will always be 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 source code.
Of course there is very little value in any text that is full of wisdom but written in such style which makes it very difficult to understand. Hence I believe that the best measure for code 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, what is relevant and what not – is fresh in the mind of the developer. She may not even notice that she has buried actual intent under layers of technical implementation details.
What are the ways to improve readability? Essentially better readability means that it takes less time to find what we are looking for. To understand what are the main topics covered in a book we don’t need to read it cover to cover. We can simply check the table of contents. In software systems this “table of contents” is formed by names and composition of subsystems, modules, methods and local variables. If all these are well composed and have intent revealing labels then they make finding the place that we are interested in much faster. For example, package names like "com.mycompany.domain", "com.mycompany.service", "com.mycompany.repository" are likely not going to help us find something very fast. At the same time 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 OrderManager or in e-mail application AddressBookService tells more than ItemService.
So code is the medium for storing knowledge and knowledge is useful only if it is easy to understand.
