Clean Coding: A Practical Introduction

Even bad code can function. But if code isn’t clean, it can bring a development organization to its knees.

Robert C. Martin, Clean Code: A Handbook of Agile Software Craftsmanship

Writing clean and understandable code is a skill that is crucial for every developer to master because with understandability comes readability, changeability, extensibility and maintainability.

Code is clean if it can be understood easily – by everyone on the team. Clean code can be read and enhanced by a developer other than its original author.

In this post, we will look at the most important principles to improve code quality..

This article is based on and draws so much from Robert C. Martin’s Clean Code: A Handbook of Agile Software Craftsmanship. It is a programming classic and I recommend you read the whole text yourself when you have time.

General rules

1. Follow standard conventions. You should be familiar with the standards of your language in terms of spacing, comments, and naming things. For many languages, style guides are available. In Java, for example, you would use camelCase, while in Python, you should use snake_case. In C#, opening braces are placed on a new line, however in Java and JavaScript, they are placed on the same line. There is no one-size-fits-all standard for these things, as they differ from language to language.
2. Keep it simple stupid. Simpler is always better. Reduce complexity as much as possible.
3. Boy scout rule. Leave the campground cleaner than you found it.
4. Always find root cause. Always look for the root cause of a problem.

Naming Things

There is a reason why we do not use IP addresses and have domain names instead: domain names are much easier to recall. And, more importantly, they can give you more information about a website. In similar vein, we use named variables in programming instead of memory addresses so someone else can understand their significance.

It can take some time to find a good name, because let’s be honest, finding a name is a hard thing, but it will save you and your team even more time in the future. And I am sure most readers have faced the situation where you visit your code only a few months later and have a hard time understanding what you did before.

Naming Rules: Variables

Choose descriptive and unambiguous names: Do not use comments to explain why a variable is used. If a variable’s name necessitates a comment, you should take the time to rename it rather than writing a comment.

Bad

var s; // screen size

Good

var desktopScreenSizeInInches;

Make meaningful distinction: Distinguish names in such a way that reader knows what the differences offer.

Bad

var money;
var moneyAmount;

Good

var moneyInNaira;
var moneyInDollars;

Use pronounceable names: If you can’t pronounce a name, you can’t discuss it without sounding silly.

Bad

const yyyymmdstr = moment().format("YYYY/MM/DD");

Good

const currentDate = moment().format("YYYY/MM/DD");

Use searchable names: Avoid using magic numbers in your code. Go for searchable, named constants. Do not use single-letter names for constants since they can appear in many places and therefore are not easily searchable.

Bad

if (product.quantity.size < 7) {
   // Do something
}

Good

if (product.quantity.size < MIN_ORDER_QUANTITY) {
   // Do something
}

Naming Rules: Functions

1. Keep them small, as small as 20 lines of code. Longer functions are likely to have high cognitive complexity.
2. Functions should do one thing. They should do it well.
3. Use descriptive names.
4. Prefer fewer arguments, the fewer the better. Three arguments are enough, but in most cases you should avoid five or more arguments where possible.
5. Have no side effects. Side effects are unintended consequences of your code. They may be changing the passed parameters, in case of passing by reference, or maybe changing a global variable. They can result in some nasty bugs if you fail to notice the side effects.
6. Don’t use flag arguments. A flag argument is usually a boolean argument that is passed to a function. Two different actions are taken depending on the value of this argument. They naturally contradict the principle of single responsibility. Consider the snippet below:

public Booking bookTicket(Customer aCustomer, boolean isPremium) {
      if(isPremium) 
       // logic for premium book
      else
       // logic for regular booking
    }

• Instead of using flag arguments, split the method into several independent methods that can be called from the client without the flag.

Conclusion

Your source code may work when it’s all messed up and full of hacks. But, it can be really complicated to carry out maintenance and even reuse this code when necessary.

Hopefully, you have picked up a tip or two today. But simply writing clean code isn’t everything, and you certainly won’t master clean coding overnight. You will need to develop this skill as a habit by keeping these principles in mind and applying them whenever you write code. Happy clean coding!