When you write program code you are telling a story. You are telling the future reader what you do, in what order, and why you are doing it. Why is this important? As software engineers we spend the vast majority of our time reading source code.
So the better you tell the story, the easier it is for your reader to understand. If the reader can pick up your story quickly, he can complete his work quickly. If the reader can follow your story easily, he can focus on his own changes. Writing code that is easy to understand and can be read quickly therefore is one of the most important skills any decent software engineer has to possess.
Kafka
Back at school I had to read books by an author called Franz Kafka. Kafka was a master of the German language. He managed to put an astonishing amount of information into a single sentence. A single very, very complex sentence. He almost always used multiple subordinate clauses in every sentence. The craftsmanship that went into his language is impressive. Often his sentences became so long that he could fill a page with just two sentences.
The downside of his style was that his texts were hard to read. I basically had to read every single sentence multiple times before I got the meaning of his words.
As a software engineer you are not Kafka. You are not payed to show off to your colleagues how good you are in solving problems in complex ways. You are payed to tell your colleagues what you are doing in a way that allows them to pick up it up quickly and move on.
Language Feature Show Off
One thing I’ve seen over and over again throughout the years is that some engineers just love to use the latest and most fancy language feature to solve the simplest problems. To this day I am not sure if this is vein attempt to impress colleagues or if the project at hand is simply used as a playground to play with the new favorite toys. Neither reason is compelling though.
As a software engineer your job is to tell your colleagues what you are doing in a way that is easy for them to understand. Use the simplest, most common language to describe your solution. Hint: in mature languages like Java or C# this is rarely the most recent addition to the language.
Asking For Directions
Imagine you are walking down the street and a car stops next to you to ask for directions to the city airport. What do you tell the driver?
Do you tell him to put the key into the ignition and turn it? To check the mirrors when changing lanes or when to shift gears? No. You assume he knows how to drive a car and these details are not of interest to him.
Do you describe to him every single house and tree he will pass on his journey to the airport? No. While this description might be accurate, it’s way too much information to him. He cannot memorize all this.
So what would you tell him? You would give him a high level summary of one to maybe five simple steps. Maybe something like “leave the village in that direction, drive on the highway, follow it for about 30 mins. At that time you should see the first road signs towards the airport. From there just follow the signs.”
This is easy to pick up, remember and follow. If the driver is unsure about any of the steps, he can ask for details for that step. No need to give him all the details.
Summary
- As software engineers we spend the vast majority of our time reading software.
- In order to be efficient we need to write our code so that it is easy to read.
- Write code in the simplest way possible.
- Use the simplest, most common language features.
- Introduce appropriate abstraction.