Truth can only be found in one place: the code.
— Robert C. Martin, author of Clean Code
Why is Clean Code So Important?
There are many reasons why you should keep your code clean, but the most obvious one is to ensure that people who read your code in the future understand it nicely. Keep in mind that these people include yourself since we don’t always remember what we wrote in the past.
Another reason is to make it easier to debug and refactor. Modifying a messy code would be a nightmare, so do yourself (and other developers) a favour by investing in writing clean code.
How to Keep Your Code Clean
Use Meaningful Names
If you like to name your variables “x”, “foo”, and other ambiguous names, please stop doing that. In fact, Robert C. Martin mentioned in his book that you should name a variable using the same care with which you name a first-born child. The point is: name your variable such that anyone reading it would know what it is used for. Here’s an example.
string text;Okay, everyone knows that it’s a text, but what is it for? Why does it exist? Its name doesn’t explain its purpose well. Let’s take a look at another example.
string lastName;Now this one is much more understandable. Even without looking at the rest of the code, we know that this variable stores a person’s last name.
Avoid Useless Comments
If your code is good enough, it should be pretty self-explanatory and doesn’t really need comments. On the flip side, if a code has many comments, it’s likely to be a bad one. See the example below.
There are several mistakes in the above code. First, the function is specifically named divide, so there’s no need to say what it does in a comment. Everyone knows that. Second, the variables’ names aren’t meaningful enough. If the variable “c” was named “result” instead, it wouldn’t have been necessary to describe its purpose in a comment.
Single Responsibility Principle
When writing a function, make sure that it’s small, simple, only does one thing, and does it well. For example, if you have a function that gets the least common multiple of two numbers, it should only do that. If you need to calculate the greatest common divisor in order to find the LCM, write another function to do that.
Write Unit Tests
Unit tests allow us to confidently refactor our code since they ensure that the tests won’t pass unless the code functionality is the same. A good method to write code with unit tests is Test-Driven Development, where the tests are written before the code itself. Read the article I wrote about it here.
Organise Your Project Well
As your project grows bigger, there are much more files and folders to manage. If not structured well, it will become too complicated to understand. Consider structuring it well from the beginning to save yourself time in the future.
Clean Code Implementation in My PPL Project
In IGRI development, we check the quality of our code with SonarQube. We try our best to make the code as elegant and understandable as we can. Here’s how we do it.
We name our variables carefully.
Our functions follow the Single Responsibility Principle.
The project is well-structured.
We implement Test-Driven Development.
Last but not least, we don’t write unnecessary comments.
Conclusion
Writing clean code isn’t easy. It takes much more effort than just coding however you like. But it’s an important thing to do to avoid stress and time-wasting in the future. Here’s a quote that emphasises this point.
Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live. –Martin Golding
Reference
This post is written as an assignment for the PPL course at the Faculty of Computer Science, UI.
