How to write code that humans understand. Part 1

Writing code is a very interesting exercise, the software industry is growing fast with all kinds of innovation from cloud computing to new programming languages the emergence of AI and machine learning, IoT etc…more and more people wants to get in the industry. People learn how to code from Learning how to write good code will distinguish you as a developer

When writing code you need to identify the two main audiences for which you are writing. I love this quote by Martin Fowler:

Any fool can write code that a computer can understand. Good programmers write code that humans can understand. Martin Fowler

The two main audiences for your code are the compiler, the computer that will take your instructions and compile them into machine code and humans who will have to read, work and maintain that codebase, the later audience is difficult to satisfy than the former and the reason why you should care about writing good code.

Write your code in such a way that you will not be lost in it when you come looking at it 1 year or 2 years later, write in a way that when you get another developer on your team he just smiles when trying to understand your code because it self explanatory. When you write good code documentation won’t be needed that much because good code is its own documentation.

Truth can only be found in one place: the code. Robert C. Martin

Here are the 5 things that will make your code look better:

  1. Mind the names

The name of a thing should reveal its intent. Take careful consideration before naming anything in your code from a variable, method, class, interface, module, feature etc... Think first about the use and function of that variable, method or class before giving it a name. Naming things is hard, i have found myself changing the names of my variables as the code grows because with the current structure of the code the name i gave to a variable does not make sense in the current context and brings more confusion than clarity. I will be writing another article about why and how to refactor code effectively where i will get deeper in maintaining the health of your codebase. Use this rule to help you come up with meaningful names: Why the variable exist and what it will be used for.

2. Avoid duplication

Ever heard of DRY? well the acronym just means Don’t Repeat Yourself. Fight and remove duplicate code by all means. Duplicate code is hard to maintain, fragile, and open your system up to bugs. Mostly we tend to copy and paste pieces of code from one location to another blindly and that’s the cause of most duplication and when a bug is introduce through copy/paste it’s very difficult to track down all the instances where that piece of code is declared so you end up fixing the bug in one location and not in the multiple places where you copied it. The rule of thumb is if you see a piece of code appear twice in different places then ask yourself a question why you have don’t find yourself writing the same piece of code twice or more and in two different places. The advantage of applying DRY to your code is when there is a change in requirement you have to make it in one place only, this saves you time, effort and increase your productivity.

3. Deal with dead code

Dead code is code that cannot be reached in the program execution, code that never run or is never used in any computation. Dead code can mislead the reader and bring confusion. Examples of dead code can be: variable that are declare and never used, methods that exist and have no references elsewhere in the code, return values that are never reached etc…in most IDE you have the ability to search for all references where the variable or method is used. So hunt all dead code in your projects remove them my rule of thumb is : only write code that you will need now not code you might need in the future.

4. KISS your code

KISS stands for Keep It Simple Stupid. Avoid unnecessary abstractions and don’t over engineer things that can be done easily. Remember not everything needs to be abstracted because with every layer of abstraction comes a level of complexity only abstract things when needs be not when you feel like it or want to be “the smart guy”. This is a trap i personally fell into when i first began to learn about software design patterns and principle of OOP, i thought that every single line of code that i wrote should follow a certain design pattern or principle and this just introduces complexity where there was no need. Some developers don’t see the need for design patterns, some have knowledge that they exist and don’t know how to use them and the other class use them every where. Design patterns used the right way can drastically improve your code quality but remember to always favor simplicity over any form of complexity.

5. Read before you write

We spend more time reading code than writing it both our own code and other people’s code.

When I Wrote It this code, Only God and I Knew the Meaning; Now God Alone Knows

To be better at writing code you need to spend time reading code. Reading out your code will help you come up with better designed names for your APIs that developers including yourself will find easy to understand and use. Ask yourself questions like does this code belong here? how will other developers use this? one exercise that helped me writing good code was reading other people’s code, by reading code not only your code you will get to recognize bad and good code. I strongly encourage you to read code, there is code all over the internet go on and start reading code you will spot good from bad if you only read your own code how will you know how to improve?

Writing quality code is not a mystery it requires time, discipline and effort from you, if you have been in the routine of doing the same thing over and over it’s not easy to embrace new ways of doing thing. Be open minded and see how other people write code wether you are a junior, intermediate or senior developer, keep in mind that the biggest room in the world is the room for improvement.

In the next parts of this article we will be getting deeper in some of the details that would make you a better developer and allow you to change the world one line of code at a time.