Clean code – When and How
When to write Clean Code
The obvious answer is: always. Unfortunately it is rarely that simple to write clean code. Good software evolves and changes as the demands and expectations move forward. You can also be faced with working in a legacy code-base with complicated and messy code.
It’s also perfectly acceptable to experiment with different solutions through trial and error.
As such there are at least two clear cut opportunities for refactoring with the purpose of achieving clean code (Besides of course writing it as you go!).
Current code in which you must provide a change
Let’s say you are tasked with implementing a change in an existing project and you are having a hard time understanding the code, let alone adjust it!
- Make sure the code is properly tested
- Start refactoring small pieces of it to cleaner code while making sure the tests are still passing
During this process you will automatically find yourself with a better understanding of the code while simultaneously improving it to much clearer code. Afterwards, implementing your changes will be a much simpler task.
Newly written code
As mentioned before, it’s perfectly reasonable to write less than clear code while looking for a solution. But you must have the will and discipline to always take the time to review your work and refactor it to a nicely integrated and clean part of the software.
We will try to make some sense of all this with examples.
First up: Naming your methods and variables!
Take a look at the following code.
The purpose of this code is to calculate the circumference of a circle as the comment suggests.
It does this by doubling the radius (given as variable ‘r’…) to get the diameter and then multiplying it by Pi to get the circumference. This is fairly basic math.
But imagine if this was more complicated business logic. You would have a hard time finding out what exactly was going on… and more importantly why it was performing these calculations.
Two main problems here:
- very unclear naming of method and variables
- obscure calculations without clear intent
I would suggest some minor changes as follows:
Simple changes. But now the goal of the calculations is much clearer. We have clarified the purpose of the variable ‘r’ by simply giving it a clear name: ‘radius’. We have divided the calculation into 2 parts to make it obvious that we are calculating the diameter first and are then multiplying it by Pi to get the circumference.
It is true that we actually added an extra line of code. But by doing so we have removed the necessity for clarifying comments. This is always a more ideal way of coding, making it clear enough that there is NO NEED for comments. The small amount of time that is needed to type out a clear name and divide the calculation can potentially pay back in massive time gains when another developer has to take the time to understand this code.
Now let’s delve a little deeper into object-oriented structuring of your code.
The rather famous FizzBuzz interview question:
Print a list from 1 to 100.
But if the number is divisible by 3, print “Fizz”
If the number is divisible by 5, print “Buzz”
And if the number is divisible by 3 AND 5, print “FizzBuzz”. Otherwise just print the number.
Below is a common, straightforward answer coded in Ruby.
Several problems should be obvious straight away when looking at this code.
- There is a lot of duplication.
- An “If-tree” that must be in a strict order with several calculations that are easy to mistype.
- This code is hard to read. You unnecessarily have to make a serious effort to understand what SHOULD be very simple code.
- It is impossible to reuse this code in case you want to solve a similar problem.
You might think it’s a waste of time to refactor this simple code. But for the sake of this example and to provide clean, reusable code for our fellow developers that will be solving the similar FazzBezz problem 2 months from now, let’s refactor to clean code!
We should start by removing those ugly calculations and “ifs” out of the Array loop. I am going to take it a step further by implementing a Class that will return the correct values.
How clear is that? The “value” function is actually almost exactly the same as our problem statement. The calculation part has been separated into its own function and it has been given a very intent full name.
Now all we need to do is initialize this class and call its overridden to_s function.
Remember our “Single responsibility” rule? One function to initialize the class, one function to loop through an array.
We ended up with a little bit more code, but added a clearly defined structure to it. The net result is easy, reusable code and a very clear intent about what we are trying to achieve.
Seems simple and easy, right? Of course, this is severely simplifying the nature of clean code. But even at this level you can achieve vastly superior code quality.
If you are TRULY intent on providing clean code for your fellow developers AND for yourself, now is the time to hit the blogs and books about Clean Code to take your programming skills to the next level!