We as programmers write a lot of code and we read more code than we write. We write drafts first then re-write them later. We remove lots of unwanted words from the code and make it shorter and more readable, not because the computer cannot understand it, but to make it more readable to others. We add footnotes to make things clear. We proofread others pull request. We try hard to come up with better names for things we imagined in our head so that it makes sense.
Even though the above paragraph describes a programmer it can also be used to describe Writers. We generally think of writing as a creative profession and programming as problem-solving, with a more methodical approach than the former. Both writing and programming is the translation of high-level ideas into words.
So what does this all mean?
Since writing as a profession has been around much longer than programming we could look them up for solutions for some problems we face. Here are few
1. Naming things
Naming things is considered one of the hardest problem in computer science. We always need to come up for name for lot of things in code variables, classes, functions…etc. Sometime this gets out of hand and we end up naming variables as data coming back months later to be puzzled on what it even means.
George Orwell in 1946 came up with six rules Rules for naming for naming things
1. Never use a metaphor, simile, or other figure of speech which you are used to seeing in print. 2. Never use a long word where a short one will do. 3. If it is possible to cut a word out, always cut it out. 4. Never use the passive where you can use the active. 5. Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent. 6. Break any of these rules sooner than say anything outright barbarous.
We can apply the same rules for naming in programming as well. This talk goes into details about this.
2. Adding comments
When we write code we add comments to it. You don’t need to write comment for every line of code. It is like writing footnotes for every line in the book it will confuse readers. When you find footnote in a book it is usually added to explain things that are not straight forward and to give you more context. Similarly we need to add code comments when code is not itself enough to explain what it does easily.
When people write books they initially write drafts just to get the ideas out and later they read it multiple times and cut out words that are not needed or add better words to explain things clearly. They don’t stop at the first draft. Similarly when we write code the first draft might not handle all cases, it will have bugs and may not be readable. But we should not stop with first draft. When we read our code again we will find gaps in our understanding and remove complex code making it simpler. Writing complex things is easy but making it simple is very hard.
If every chapter of the book is written in different writing style it will confuse the readers. Sometimes we may want to repeat the same words to increase the readability. But sometimes we just add a reference to previous chapters so that the readers who have been reading through the chapters can understand it without reading the whole text again. Similarly in your code, we should stick to a particular coding style to make things consistent. Sometimes developers overdo the Dry principle. This will cause confusion. Instead, we may sometimes want to allow code duplication whenever it is really needed.
There is a lot more things than mentioned here that we can learn from the writing world. This is just to give a glimpse of the similarities between seemingly different profession and what we can learn from each other.