The world’s leading publication for data science, AI, and ML professionals.

Take Your Programming Skills to The Next Level

Develop simple, scalable, easy to read and also easy to maintain codes by following simple Clean Code principles.

Programming Skills

Photo by Nicolas Cool on Unsplash
Photo by Nicolas Cool on Unsplash

Have you ever visited a function that you have written recently? Maybe you needed to update a function. But, you left the code as it is, by using the "If it works, don’t touch it" principle since the code is quite complex?

If you were to open your legacy codes right now, could you understand them right away? Or maybe you need to spend at least a few minutes to remember what the code is all about?

If you need to spend more time than a glance, then probably this article is for you. Here we talk about the ways to understand your legacy codes without wasting your time.

Image Source: Nick Pappas on Quora
Image Source: Nick Pappas on Quora

If you follow the principles we describe in this article, probably you won’t need to waste any more time to understand your legacy codes since they never become obsolete.

Photo by Nong Vang on Unsplash
Photo by Nong Vang on Unsplash

Recently, I have started to create a library. Over time, the library has exceeded thousands of lines. And interestingly, as the library got more advanced, some unexpected problems started to arise.

As the scale of the code grows, it takes much more time to implement new functionalities.

Since the library is at its development phase, it could potentially have miss behaving functional parts.

For example, a function could fail because of extreme input values that are not being thought of in unit tests.

That is why, whenever I implement new functionality that uses some other parts of the library, first, I need to spend some time to understand the related functions.

Photo by George Pagan III on Unsplash
Photo by George Pagan III on Unsplash

After reviewing a new function and handling the failing parts, some time passes and other parts of the same function get broken.

When I come back to the recently refactored function, I find myself remembering almost nothing. I have to review the same functions all over again.

The problem resulted in me going back and forth to understand what some pieces of code snippets were doing most of the time.

At some point, I have stopped and started to search for what was wrong.

Photo by Nicolas Cool on Unsplash
Photo by Nicolas Cool on Unsplash

When I was searching for a solution, I have found a "Clean Code" video course [1] that is prepared by the writer of the Clean Code book [2], Robert C.Martin.

Finally, with the help of the Clean Code video course, I have solved all my problems. No more bad implemented code that results in me wasting time.

The solution is The Clean Code

Here I have arranged a few of the critical rules from the Clean Code series which I still remember even after weeks. By just applying the Clean Code principles, all of my problems have been solved.

Never waste time to understand a function’s behaviour with the help of the Clean Code.

Photo by Dollar Gill on Unsplash
Photo by Dollar Gill on Unsplash

1 – Naming

Every variable, class and function name should describe itself. [1]

Photo by Guillaume TECHER on Unsplash
Photo by Guillaume TECHER on Unsplash

Let’s start by reviewing the following piece of code which I have written before taking the Clean Code video course.

Here we can see that we have a Netflix dataset and it provides a method to load movies inside of the dataset file.

When we look deep inside of the function’s implementation, it is kinda hard to grasp what it is exactly doing at the first glance.

Let’s now take the following code snippet, Example 1.1, which is doing the exact same thing as Example 1.

At the code Example 1.1, again we have a Netflix dataset that loads the movies. But, this time the moment we look at the load movies function, we can understand what the code is doing in detail.

See the code is like an English script.

You don’t even need to read any code other than the first 7 lines to understand what the code is doing in contrary to Example 1 where we need to read all of the 12 lines and also figure out what the code is doing.

Photo by James Barnett on Unsplash
Photo by James Barnett on Unsplash

In Example 1.1, we see that we have long named helper functions that are only intended to be used by this load_movies function.

Since no other function will ever call these helper functions, we can name them as long as we want, right?

At the end of the day, no one ever calls them again, we just call them here to give meaningful function names and also make the code more descriptive in itself rather than needing any comments.

Also, a programmer often needs to understand what the load_movies function is doing rather than understanding its implementation details like how to convert format and how to read data from an input file exactly.

If a programmer likes to figure them out, then the programmer can always visit the respective private functions which are only intended to be used by load_movies function.

Photo by David Travis on Unsplash
Photo by David Travis on Unsplash

For short, we should have long and descriptive names with private functions which will be called once or twice.

Also, we should have short and concise named public functions since they will be called many times by different programmers.

Lastly, functions should have no more than 2 to 3 parameters to increase readibility.

2 – Comments

Commenting means failing to write clean code. If any comment exists other than inside of public API, accept your failure. [1]

If any comment exists, then it is critical to know. [1]

Photo by Thiago Cardoso on Unsplash
Photo by Thiago Cardoso on Unsplash

Let’s review the following code, Example 2. Again you don’t need to understand it at all. Just by looking at the code, we can see that there exists quite a lot of comments to make the code more understandable.

Here in Example 2, we see that there is a time constraint on data that could be either time-bin constraint or max-limit constraint.

To understand the code, we need to read every line of the code including comments. Even after reading it all, you may still be not satisfied with the purpose of this time constraint in detail.

Let’s now examine the following code which I have written after applying Clean Code principles.

Here we see that there exist two types of TimeConstraints depending on the interval. If the interval is valid and is of expected type then the constraint is met otherwise the constraint is not met.

"Here the only thing I have done is to try to remove comments."

As you can see, the 17 lines of code which have no comments and no complex code convey the same information as the 58 lines of the old version of the code.

The following code snippet is the rest of the code of Example 2.1.

Since our aim was to understand what was TimeConstraint class is doing, we never even needed to review this code. Because, from its name Interval, it is quite clear what the class is all about.

3 – Function Length

Reduce the function length as much as possible until you can’t.[1]

Optimum function length is 4 to 10 lines.[1]

Photo by Shahadat Rahman on Unsplash
Photo by Shahadat Rahman on Unsplash

Let’s review Example 3, which loads the user movie rating data of Netflix Dataset.

Here we see 49 lines of the long load_ratings function. What exactly this function is doing to implement its functionality is quite obscure. We need to read every line of code to comprehend it thoroughly.

Let’s now examine the newer version of the code, Example 3.1, which follows the Clean Code rules.

Here we see that

we have 7 lines of the long load_ratings function. The load_ratings function itself describes what it is doing quite nicely with no comments. We don’t even need to read other private functions to understand the code.

4 -File Length

Files should be 50–100 lines on average, at max 500. [1]

Photo by Maksym Kaharlytskyi on Unsplash
Photo by Maksym Kaharlytskyi on Unsplash

Last but not least, let’s now review a file of code from a recommendation system library Surprise.

Here in Example 4, we can see that the code snippet is above 700 lines!

Try to read the code snippet and you will most likely get stuck by the long comments.

  • It includes incomprehensible formatting comments for the documentation of the library.

Even though from the point of the designers of this library, it could be easy to put documentation right inside of the code, it does make the codes hard to read, and also results in big long files.

Never put HTML or any formatting text inside of the comments. It makes the comments and also codes hard to read.

Changes After Applying Clean Code Principles

The following symptoms started to arise within my code after applying Clean Code principles in the following weeks:

  • Code is perfectly readable by anyone, not just by programmers.
  • No one needs to read more code other than the function they want to understand.
  • The Code looks simple, nice, and short.
  • No code file looks intimidating and hard to understand.
  • Any functionality can be constructed easier than ever.
  • Scaling is also quite easier.
Photo by Nghia Le on Unsplash
Photo by Nghia Le on Unsplash

Do The Clean Code Principles Work?

From the point of me, it is perfect to understand what the 58 lines of bulky code are doing by just reading 17 lines.

These principles make the code more maintainable, cleaner, simpler, and also low cost because no programmer will waste time understanding it.

Before using Clean Code principles, whenever I came back to an incomprehensible code snippet, I wasted quite a bit of time to understand the code while in that time interval I could have designed and implemented new features to a project.

Photo by maria paula contreras on Unsplash
Photo by maria paula contreras on Unsplash

The Clean Code Principles

All in all, I can say that by just getting used to the Clean Code principles that I have summarized down below, you can create more professional code as you have witnessed.

The resulting codes are simple, scalable, easy to read, and also easy to maintain.

1- Every variable, class, function name should describe itself.

2- Functions should have no more than 2 to 3 maximum parameters to increase readibility.

3- If any comment exists, then it is critical to know.

4- Commenting means failing to write clean code. If any comment exists other than inside of public API, accept your failure.

5- Reduce the function length as much as possible until you can’t.

6- Optimum function length is 4 to 10 lines.

7- Files should be 50–100 lines on average, at max 500.

8- Never put HTML or any formatting text inside of the comments. It makes the comments and also codes hard to read.

From my hundreds of different Github code inspections, I have realized that almost none of the programmers follow all the Clean Code principles.

Try as many of them as possible in your code and see if the symptoms I got arise with you as well.

These principles are by no means a comprehensive list for improving your Programming skills. These are just a tiny fraction of all techniques shown in the Clean Code series. There are tons of other techniques which would improve yourself even more.

Photo by Cristofer Jeschke on Unsplash
Photo by Cristofer Jeschke on Unsplash

Towards The End

I hope you now have the motivation to start learning Clean Code principles and improve your programming skills to a great extend.

Try applying the eight clean code principles and feel free to share what do you feel about them.

Imagine if you could learn how to make sure everything always follows these rules by using some surprisingly interesting techniques defined in the Clean Code.

You can discover how to implement these principles in detail, by taking the video course or reading the book that we give reference down below.

Further Studies

Growing Professional Programming Skills

[1] Robert C.Martin, Clean Code Video Series(2016)

[2] Robert C.Martin, Clean Architecture: A Craftsman’s Guide to Software Structure and Design


Related Articles