Your codebase should read like a great book.

It has often been said that the greatest communicator known to mankind is the written word. Words can be so powerful, it is through words that wars have been waged and ceased, it is through words that great and powerful truths have stood the test of time, and it's through words that we communicate our innate being with one another. Words are powerful, and they matter.

I'd like us to think about our codebase, not as code but as words, and see how it holds up to any great book.

Think of your favourite book, it probably has a central theme, it's clearly defined, and takes you on a journey through time (and sometimes space). The words on each page have been carefully chosen and crafted together to create a compelling narrative that seeks to communicate something to the reader.

Why should our codebases be any different?

I believe we have misaligned our priorities when it comes to how we develop software. In the vanity of chasing ever-increasing features, ever-increasing "best practices" and ever-increasing workloads, we have succumb to the wrong priorities.

We have fallen into the trap that by merely choosing the right framework and tools we can guarantee success (or rather that the way we choose these things have become misaligned), that the processes we need to hold everything together as we continue to fragment our work is the right way to go. That slicing everything into little pieces and distributing them can in any way produce a coherent and unified product. That this is the only way to do things.

Comparing this to writing a book highlights the fallacy of such an approach. Imagine writing a book whereby each paragraph is written in isolation by lots of different authors, and then pieced together by lots of different editors, each person with a slightly different outlook. It's ridiculous really.

As we look at each page we realise that we can only read certain words of a sentence, some words are written in a different language and some words are jargon we don't know. It ends up being hard to engage with and we give up or drag ourselves through, we certainly don't enjoy it.

There aren't many books that are rich with jargon and abbreviation that are a pleasure to read, these things are barriers for people and make it hard to transport yourself into that environment.

When a codebase is put together, it can be so easy, especially under tight deadlines to do the same, to only focus on it working. However as with writing a book, merely putting words on paper doesn't mean success. Thought and care, coupled with vision, is needed in every interaction to achieve something coherent.

That's why I believe we need to refocus our priorities and consider that making something work is only the entry floor, we need to work diligently on ensuring that how we communicate (that is the code that we write) is appropriate and tailored to the individuals that will be reading it.

Ensuring things are clear and coherent will go a long way to achieving something great. It can be extremely difficult to achieve this, especially if your organisation structure permits lots of voices and opinions pulling in every direction but it's worth it every time.

Considering that the majority of what we do at work is reading and discussing, it affects everything that we do. Where problems arise is when there is ambiguity and misunderstandings that aren't dealt with, ensuring those are minimised and things are clear is one of the greatest things you can do to cause success.

Let's spend more time and energy on crafting a holistic viewpoint, on the words that we choose, on the story that our work tells. Let's program for the human, not the machine.