Want to Write Better Code?

In over twenty years of working with enterprise software development, the biggest problems I have seen in the code aren’t to do with obscure bugs in the languages or the frameworks used (though they are often memorable). Nor are they related to the performance of the software. No, the biggest problems are generally due to the readability and maintainability of the code and, most critically, due to a poor representation in the code of the reality that is attempting to reproduce.

I realise that is a bit of a philosophical statement when talking about code, but then this is a bit of a philosophical article in many regards. However, it also a subject that really isn’t talked about a great deal and one that, if more developers had a better grasp of, would result in a generally higher quality of software.

Like it or not, when writing software, the developer is building (in addition to hopefully working the software of) a mental model that both they and anyone else maintaining that code in the future will need to understand and hold in their mind at any time they work on the code in question. The critical part here is not so much the complexity of that model, but how well that model maps onto reality. The closer that mental and software model is to reality, the lower the cognitive load the developer endures and, therefore, (usually) the lower the number of bugs introduced.

Further, as this mental model deviates from reality, not only do you start to introduce additional complexity in the logic of the code to correct for the deviation (increasing the probability of introducing a bug), you also further increase the cognitive load on the developer, thereby increasing the cost of maintenance of the codebase.

This may seem obvious and, in the main, developers will usually attempt write code in ways that maintain a clear mental model. At least when the code is first written. With the passage of time and evolution of both code and reality, it is common for the two to diverge. Whilst most developers will aim to initially write code that bears a clear reflection of reality, as enhancements are made to the code (often to cover a changing reality), far fewer developers are brave enough to change the structure of the codebase to continue to ensure that it still reflects the new reality. Far too often what happens instead is that a minimal change to the logic of the code will be made to accommodate the new requirement. These changes slowly add up over time until the software model no longer bears any resemblance to reality. The way in which this change builds up over time can be quite insidious and requires an attentive developer to ensure that the model continues to reflect reality.

Often, relatively simple changes, such as renaming a class or even a variable, can lead to significant reductions in cognitive load (and assumptions in what functionality that class provides by new developers). Other times, greater imagination may be required. Often, the reality that is being modelled is not as simple as real physical constructs that can be seen. Instead, what needs to be modelled may be a business process (which in itself may not be well-defined) or other abstract concepts which may be difficult to visualise.

As a side bar, I want to highlight here that the additional effort made by developers to create a clear mental model is rarely appreciated let alone applauded. Partly this is because few developers, product owners, scrum masters or managers appreciate the difference this makes, but this is largely due to an aspect of human nature. Creating a complex model that takes time to explain to people will often attract criticism and improvement of the model. Creating a model that is so intuitive that it immediately makes sense usually results in thoughts along the lines of “well of course, that’s the obvious way to do it”. It may, however, have been far from obvious and required considerable effort to develop a model that results in such a clear mental image.

The real challenge then, for the developer, is one of creativity, and it is this that I want to really focus on for the remainder of this article. To be able to write new code that models what is often abstract, or even harder, to change existing code to accommodate changes to that abstract reality, requires a large degree of creativity and innovation from the developer. No amount of reading design pattern books, knowledge of frameworks and APIs will solve the problem. If the developer is unable to devise a model in the software that requires the minimum amount of code to be written, while still reflecting reality and posing the smallest possible cognitive load on future developers, the resulting software will likely be expensive to maintain and buggy.

I would go so far as to say the biggest difference between the mythical 10x developer (and yes, they do exist) and an average developer is their ability to perform this feat. That reduction of cognitive load (not only for future developers) but, critically, for themselves provides an acceleration to the coding process that easily provides (if not exceeds) that 10-time productivity boost.

So, how do you get better at this and why aren’t there more books, article, blog posts and YouTube videos teaching developers how to do this? A part of it is certainly through understanding well-known patterns and knowing when to apply them (and when not to). A larger part though is really just exercising the creative muscle of the mind and being innovative. This is hard to teach.

Like any other skill though, it can be improved with practice. Practising innovating. Practising creativity. If you want to be better at writing code (or designing and architecting complete systems), you need to flex that creative part of your brain as much and as often as possible.

This could take the form of spending your evenings and weekends doing more of the same (writing code) and, sure, that might help (provided you actually attempt to do things in new ways rather than reproducing the same patterns you’ve used in the past). Personally though, I like a little more variety in my life than just writing code or creating software architecture. More importantly, there are more ways to be creative and the greater the variety with which you practise your creativity, the better you’ll be at it (even when writing code).

So, if you want to write better code, take up woodworking (but design your own projects), or writing poetry, or pottery or painting. In fact, the further that it is from writing code the better. Spend your evenings and weekends instead writing a symphony or putting together a new dance routine or even just remodelling your home. Grab opportunities to be creative in other areas of your life and build that creative muscle.

If you’re looking to hire new developers, stop fixating on the academic qualifications (a computer science degree is completely not necessary for a start and, personally, I’d rather hire someone without one) and dig a little deeper. Ask the candidate to answer questions that require them to construct mental models and see how understandable they are. If you’re looking to improve your current development teams, make sure they’re in an environment that’s conducive to unstructured creative thought. Encourage them to leave the office at 5pm and go do something creative outside. When building diversity in your team, try and include diversity in their interests outside of writing code.

The best software developers I’ve worked with are not computer science graduates and they often had interests such as dance (bachata in that particular instance), woodworking or writing.

Want to write better code? Go and compose a symphony.