Mindware Engineering
Coding is Storytelling
Code like you are writing a story
When you have an idea, you want to tell the world about it. And you will use language to do so.
Language is a force that moves history forward. We can motivate ourselves and other people, share our experiences and explain reality. We use language to talk about things that don’t exist and then bring them to life. We can tell stories about anything.
I like to think of designing a system as telling a story. A story that is written in a programming language.
And just as every story requires a listener, the code always assumes a reader.
Who is a reader?
Naturally, the first reader of your code is you. You start with an idea, think and code it. Even when you write a one-off script, later, you may need to change it.
If you work with a larger project, you have teammates. You are evolving the story of the system with your code. You add storylines and write new chapters. And your teammates will be reading the code you are writing.
With time, you and your team will spend more and more time rereading and rewriting. With time, the cleanliness and clarity of your code will have more and more influence on software quality.
Software Quality
Has this happened to you? You open some code to make a change or implement a new feature,and you understand within 3 seconds that it’s going to be hard.
Here you are bumping into the structural qualities of the code. Qualities that we are striving to achieve are simplicity, maintainability, and evolvability. These qualities allow our software to serve its users and make up the non-functional quality of the software.
Functional quality is the plot of our story. A story that tells what software can do for its users, with features and user flows, use cases, and business rules. And functional quality indicates how our story meets users’ requirements.
The quality of a story starts with the ability to read and understand it. And we do have similar expectations from the code.
First, let’s look into the reading process itself.
Reading
How do we read?
The way you express your thoughts influences how readable your writing is. But the process of reading itself has its own limits. First, we don’t read text, we scan it.
We dno’t raed ervey lteter. The first and last letters must be in the right place, but the rest can be a mess.
This also applies to the sentences. We read by dividing the words into clusters of 2 to 4 words at the time. Most people can decode 4–5 pieces before needing a break.
We don’t like to read stressful paragraphs like this. The following text is just a sample to show how hard and time-consuming it is to read this long text. It is not easy for the human eye to scan, and we feel that we don’t want to read long text even in the beginning when we first see it. And I can totally understand it, it is horribly painful.
Because of this scanning ability, you can tell that code is bad without even reading it.
Brain limits
Our thought process also has constraints. This is how our brain is working. And it is important to remember brain limitations.
- We can process just one thought at a time. Yes, we also can switch quickly between thoughts.
- We have thoughts that are 3 seconds long.
- Our working memory keeps only 5–7 items.
We are suffering from a cognitive load. And it is super important to reduce non-significant details and structure information for better understanding.
Let’s assume that reading code is similar to reading text, and let’s take a high-level view on how to make text better.
Text
Articles about how to write articles.
If we read up on the topic of how to write a nonfiction article, we’ll probably find advice to keep this simple. This will also apply to writing code.
All writing is a question of solving a problem. It might be a problem of tone and style, or finding the right word.
Use simple words. Most texts on writing style encourage authors to avoid complex words. Increasing the complexity of the words doesn’t make you more intelligent.
Use shorter sentences. The benefit of short sentences is clarity. Directness. Or better, make it as short as possible and as long as necessary.
Structure your writing. This is essential in order to create text that flows. Create high-level structures containing introduction, theses, and conclusion. Create a rhythm with headings and subheadings.
Rewriting. Rewriting is the essence of writing well. We all have a bias in favor of a first draft or a first idea. But a newly written sentence always has something that can be improved.
Good writing is like math: it has logic and structure.
Language
The plot of the story is behind the words. You set up characters, build relationships and describe the exterior.
It seems that our brain is specialized in dealing with complexity in natural language. When people are talking, they discover differences in interpretation and in the meanings of the words being used. Even when people of different languages come together to communicate, they invent a common language, called pidgin.
A lot of paradigms in programming and modeling use a natural language as a way of design.
Modeling with natural language.
You can start to investigate the business process with Event Storming. This is a framework that allows building a model of a domain. And it is done by communication between domain experts, developers, QAs, UX designers, and any other parties. As an outcome, you will have a better understanding of the events, roles, and processes of the system.
Event Storming sessions will help to develop Domain-Driven Design. It is a modeling approach focused on the business domain. It uses Ubiquitous Language as a common way of describing a business area. This language makes a connection between the business description of the domain and its architecture. You will have the high-level design of the system.
You can use user stories as an informal, natural language description of the features of a software system. They are written from the perspective of an end-user or user of a system. It can be formalized with the use cases for particular flows and parts of the software. Usually, as a list of actions or steps with interactions between objects in a system.
On the components level, Clean Architecture by Robert Martin can be an approach to system design. One of the main concepts is Screaming Architecture, which states that the architecture of the system must tell what it does. It helps to build systems with high cohesion and low coupling.
On the code level, type system and polymorphism will help you to construct nouns, verbs, and adjectives of your code language.
Final thoughts
A language is a natural way to structure and explain information.
We use the same words to tell a story, model a system, and code an application. We hide complexity behind the words-abstractions, and we want to make our code more readable and focused.
To develop a great application we communicate a lot between business, tech people, designers, and others. So putting an extra effort to make our system readable on all levels from architecture to the code is worth it.
Thank you for reading! Share you thoughts with me on LinkedIn or Twitter.
More reading
If you like this article you can be interested in the following.
Originally published at https://pavelfokin.dev.
