Principles of Clean Coding — Every Entry Level Developer should Follow (Part 1)

While reading the book “Clean Code — by Robert C. Martin” I made a list of some points worth sharing.

We are Software Engineers, we are expected to be smart with a strong logic building and problem solving skills. But when you are contributing to a large code base of an organisation, your code should be readable as well. You need to follow a set of coding standards set up by that organisation while writing your code. It’s not only about optimisation, it’s about keeping it clean as well. There is a team behind that code base you’re contributing to, so if we all stick with a fixed coding standards then it will make things easier for all of us in the long run. This book “Clean Code” has explained beautifully why writing clean code is essential and how failing to it can lead to some serious problems.

In this article I will explain some key concepts which I picked from the first 3 Chapters of this book. If you’re an entry level software engineer or aspire to become one in near future, I would suggest you to go through the concepts mentioned here and follow them when you code next.

They may defend the schedule and requirements with passion; but that’s their Job. It’s your Job to defend the code with equal passion.

There will be Code

The author has argued that we won’t be able to build a machine that can do what we want rather than what we say. They will never be able to translate vaguely specified needs into perfectly executing programs that precisely meet the needs. Hence code will exist and there will always be code at the end. Now, here the author has made pretty clear to us that code will going to exist and we can’t skip that, so now that makes essential for us to be able to write clean code.

Bad Code & The Boy Scout Rule

We often write bad code due to several reasons like an approaching deadline, intolerant customers and many more. Programs must be written for people to read and only incidentally for machines to execute. We should spend a considerable amount of time thinking what we are writing and whether there’s a way to make it more clear. If we are not doing that, then it’s our fault and we are being unprofessional here. The only way to go fast is to keep the code as clean as possible at all times.

Clean Code is simple and direct. Clean Code reads like well-written prose. Clean Code never obscure the designer’s intent but rather is full of crisp abstractions & straightforward lines of control.

It’s not enough to write clean code. The code has to be kept clean over time. The Boy Scout of America have a simple rule that we can apply to our profession : Leave the Campground cleaner than you found it.

The Boy Scout Rule states that, if we all checked-in our code a little cleaner than we checked it out, the code base simply could not rot. Change one variable for the better, break up one function that’s a little too large, eliminate one small bit of duplication, clean up one composite if statement.

Using Intention-revealing Names

Choosing a good name takes time but saves a lot more than it takes. The name of a variable, function or class should tell you why it exists, what it does and how it is used.

If a name requires a Comment, then the name does not reveal the intent

Suppose we are working on a code snippet of a Minesweeper Game. We are writing a module that fetches all flagged cells from the game’s board. Here is the initial module with bad and confusing names.

In the above module we can’t get any idea about what the module is doing, what the lists are storing and what the function returns finally. Now in the next snippet we can see how the readability is enhanced when we spend a little more time while thinking of intention revealing names.

In the above module we didn’t made any major changes in terms of logic. Just changed some variable names and function name, and boom! Now the module looks so much readable. We can clearly tell that the function fetches the flagged cells from the game board after checking the status of each cell.

Avoiding Disinformation

Programmers must avoid leaving false clues that obscure the meaning of code. Do not refer to a grouping of accounts as an accountList unless it’s actually a list. If the container holding the accounts is not actually a List, it may lead to false conclusions. So accountGroup or bunchOfAccounts or just plain accounts would be better.

Number series naming ( a1, a2, ….., aN ) is the opposite of intentional naming. Such names are dis-informative. In short we should avoid using those variable names which could not explain it’s own existence. Below is a code snippet which is somewhat dis-informative.

Now, let’s make the above module a little more informative.

Here, the above module clearly tells that it copies the characters from source character array into the destination array.

Classes and Objects should have noun or noun phrase names. Methods should have verb or verb phrase names.

Picking One Word per Concept

We should choose one word for one abstract concept and should stick with it. For instance it will be confusing if we have fetch, retrieve and get as equivalent method for different classes. All the three words means the same thing and hence we may get confused about which one belongs to which class. Hence it will be advisable if we stick with one among the above three words for all our classes.

Functions — Do One Thing !

We all have written functions in the past. Clean Code suggests a lot of things which we can take care of while writing a module or a function. The first and foremost thing is that our function should perform only one task i.e. it should follow Do One Thing rule. If we follow this then we can automatically achieve the next thing, i.e. to keep our function small. There are many times where we intend to make a function long. If that happens then we can investigate further and check whether it performs multiple task or not, if it does then split it into multiple separate modules performing those multiple tasks and everything will be fine !

FUNCTIONS SHOULD DO ONE THING. THEY SHOULD DO IT WELL. THEY SHOULD DO IT ONLY.

Function Arguments

We all pass arguments to a function when there is a requirement. Do we really need to think about the number of arguments we are passing into the function. Clean Code says that an ideal number of arguments for a Function is zero (niladic). Next comes one (monadic), followed by two (dyadic). Three arguments (triadic) should be avoided where possible. More than three (polyadic) require very special justification — and shouldn’t be used anyway.

Whenever a function seems to need more that two or three arguments, it is likely that some of those arguments ought to be wrapped into a class of their own. Below is an example where we reduced the number of arguments passed into a function.

We can see how we reduced the arguments by wrapping the two arguments x and y into a single Point object.

Signing Off

These were the few concepts which I wanted to share. So long, I find Clean Code to be an amazing guide and we all can take a page from it ! If you’re a college student and aspire to be a Software Engineer in future then these concepts may help you a lot in your future job. You all ready aim to optimise, this will make you clean as well.

Make it Correct, Make it Clear, Make it Concise, Make it Fast. In that order.

There is a lot more to it. This article comprises of some concepts from the starting 20% of the book. I will write the next part of this article soon (Once I finish reading the Book!).

I hope you find it useful and Thanks for reading it till the end, We came a long way though !