A deep dive into Coding Standards for writing Clean Code

We write code. Lots of code. To meet the stringent deadlines, we end up writing working yet messy code. And then we say it to ourselves, “I’ll clean up this mess later on”, which of course doesn’t happen for most of the time for the very sole reason — We’ve got more and more things to code.

LeBlanc’s law: Later equals never.

What you need to understand is, You will not make the deadline by making a mess. Indeed, the mess will slow you down instantly and will force you to miss the deadline. The only way to make the deadline — the only way to go fast — is to keep the code as clean as possible at all times and that too from the very beginning. But how? Let’s discuss in detail, some standard guidelines for writing clean code.

int x? What is this sh*t bro?

Yes, you read that right. And that’s what most of the Senior Software Engineers and Engineering Managers feel when they review your code. Let us start from the very ground level; Naming!

What’s in a name? That which we call a rose by any other name would smell as sweet. — William Shakespeare

Exactly. That’s where most of the developers fail. Naming is an essential part of our goal to write clean code.

Which of the two snippets do you think represents a better way of declaring a variable? 🍫 for you if you chose the 2nd snippet 🤥

• The name of variables should be such that it clearly reveals the intent behind creating that variable.
• Avoid variable names that need comments to support them.
• Try to choose a name that specifies what is being measured and the unit of that measurement.

Now consider the above set of snippets. If you didn’t know the context of writing a variable name such as “hp”, how would you know what does it denote? Your best bet here is to Avoid choosing short forms of words even if they sound ‘good’.

Any guesses for which of the two is a well-formed method prototype? Of course the second one because its arguments clearly represent what they mean. The next tip to write clean code is to make use of pronounceable and searchable names in your code. The following example demonstrates the same.

In the above set of snippets, it may seem that Snippet might just be better due to less number of lines of code. But it is to be noted, that the lesser the number of lines of code, the higher the chance of the code to be a mess! We can look at a couple of things in Snippet 1 that are make it look clean. First, the variable names exactly depict what could be their use case. Second, defining an additional variable (i.e. NUMBER_OF_DAYS_IN_WEEK) makes the code even more readable.

Context Attachment can do wonders!

Yes, it may increase the number of lines of code or files in your codebase but it's actually a very effective way of writing clean code. Let’s discuss in detail what I mean by this.

Have a look at the above snippet. What can you interpret from the variable name defined here? What state does it talk about? Solid? Liquid or Gas? Some state of India? State of your mind? Your girlfriend’s/boyfriend’s mind? (Wish you could know that! 😜) Jokes apart, have a look at the code snippets below. Do they seem clearer now?

Yes, of course, they do! Either one of these works fine. More precisely, if you have a large number of similar variables, consider grouping them into a common class as depicted above in Snippet 1. More on this in the following section(s)😋Also, if you think it’s not viable to create a separate class (for example, if you have only a few variables to deal with), you could follow something as depicted in Snippet 2. Here we simply add a partial-suffix which almost clearly tells what does this variable denotes.

Can you start, drive and stop your car through a single point of control?

Well unless you own an AI-driven car, I guess you can’t. 😛 Same is the case with methods. One method must always do just one thing. And here comes a really important concept of SOLID principles: The Single Responsibility Principle.

According to Wikipedia, The single-responsibility principle is a computer-programming principle that states that every module, class or function in a computer program should have responsibility over a single part of that program’s functionality, and it should encapsulate that part.

So in short, how do you write good methods? It involves quite a few things to consider. Let’s go through each one of them one by one.

• One, the method must always do just one thing. No more, no less. Your method should never show a glance of temporal coupling.
• A method name and its body must always clearly depict what does the method does.
• The number of arguments in your method should be at most 3. In fact, the lesser the no. of args, the better and cleaner the method is.
• Avoid passing booleans (or flag values) to arguments of methods.
• If more than 2 or 3 arguments are to be passed, it is likely that some of the arguments have similar behavior. In that case, we can wrap the arguments in a single model class to reduce the number of arguments. A good example to illustrate this is shown below where Snippet 2 represents an improved version of Snippet 1.

• You may have a question if the following code is clean w.r.t. number of method arguments:

And my answer is, yes it surely is! The thing to be noted here is that, in methods like these with var-args (or variable arguments), we theoretically group together the var-args parameters to be of a single common type hence narrowing down the number of arguments in the method to 2.

• And the last point to consider is, your method should either do something or answer something, but not both at the same time. The following example demonstrates a method doing both of these things which shows signs of poorly written code.

Only if a car could walk!

No, they can’t unless it's a transformer car. 😛 Let’s now discuss some clean code principles related to classes. In the following section, we will see how can we write “clean” classes just like we saw in methods.

• The first and foremost principle to write “clean” classes is the same as the one we followed in methods. Browny points for you if you guessed it as SRP! A rephrased version of SRP in terms of classes is quoted below:

Single Responsibility Principle states that a class or module should have one, and only one, reason to change which further implies that Classes should have one responsibility — one reason to change.

It is to be noted that following SRP also means that we increase the potential of a class to be reused again at multiple places in our codebase, hence making our code even cleaner, and easier to play around with.

The above code snippet is a good example of a class following the Single Responsibility Principle.

• Classes should be highly cohesive. When cohesion is high, it means that the methods and variables of the class are co-dependent and hang together as a logical whole.
• When classes tend to lose cohesion, split them!
• Classes should be open for extension but closed for modification. This aligns with the second principle of SOLID: Open Closed Principle.
• Classes should depend upon abstractions, not on concrete details. This aligns with the third principle of SOLID: Dependency Inversion Principle. It also means minimizing the coupling between classes. This concept may also be referred to as Change Isolation. For example, we should make our classes depend on interfaces whose implementations are hidden from us.

The above snippet illustrates the last point we discussed. Here, every class that needs to access RemoteDataSource will access it via the interface RemoteDataSource hence hiding the core implementation of its implementing class RemoteDataSourceImpl from outside classes.

And if you have come here, a big congratulations for making it here! Coming to the very end of this blog, I’d like to say that following the coding principles is not something you can learn to do overnight. Start by following small bits of it in whatever you code every day and you’ll see it showing results in some time. 🚀

Finally, thanks for reading this blog 🧡 I hope this blog helps you to become a better programmer! 😄