English | EN 
Writing code is easy, writing good code is hard. Many books have been written on proper code quality, design patterns, structure, architecture. And of course, it has its place – when we have rules, we can test it, we can automate it, we can check it. The pitfall here is that the goal is often moved to satisfy that system, rather than delivering proper code, especially in the software factories of this world.
Prior to even the notion of computers, there was art and literature. The main challenge that is shared is not to store information, but to make the information appealing to the audience. One can write a book that contains a lot of information but if it isn’t appealing it will not be read.
Writing good quality code is an art form, like making a beautiful painting or writing a book. You want the application / story to be readable, you want to get that logical structure, but most of all you want to give others pleasure in reading and understanding it, as it will be maintained for some time to come – hopefully. In order to do that, I want to give some pointers that have helped me a lot:
Your editor is a canvas, make it pleasing to the eye
When text is pleasing to the eye and well-structured, it’s easier for the reader to see what’s going on. I would like to summarize them giving code examples. Principles I apply are:
- MECE (Mutually Exclusive, Collectively Exhaustive) ordering of information like constructor parameters and functions – this dramatically improves readability, these listings are much easier to scan.
- Consistent variable names – long names and changing them all the time makes it hard to understand what’s going on. If something has a general or similar purpose, don’t give it specific or inconsistent names.
Compare this example:
With this:
Treat your code base like a book
When you read a book that has a poor index or structure, it’s hard to read. If you would have an encyclopedia that had abstract chapter names where each would contain either one item or 50 pages without substructure, you would never use it. The same goes for a code base. Your directories, namespaces and modules are like chapters in a book. Write your application accordingly:
- Keep levelling consistent, it’s weird when some part has deep structuring when other parts are all in one directory.
- Once again, MECE helps understand things. When you want a subdivision, make sure it is a sensible one. Same goes for methods in an interface as well.
- It’s weird when a directory of namespace only has one or two objects in them, this is usually a sign of appendages.
- The content of a book and its chapters follow some structure, the same could be said for code. Make it predictable where to find things.
Zoom out
In your day to day activities as a developer its easy to get lost in the details. However, given the amount of time you spend on a code base and the (change of) people involved, it will most likely lead to crooked code. This is not related to the quality of someone’s skill, but the poor fit over time of changing insight.
One can only imagine how Michelangelo would have painted the Sistine Chapel if he didn’t have the overview from start to finish, if he only focused on the details and not the complete picture.
