This blog is based on the book by Robert C. Martin (Uncle Bob).
A familiar set of circumstances which I see is as follows. The client asks for a new nice simple feature, so I write a small method which fulfils what they ask for. When they are testing this, they realise that they did not clearly communicate their needs, so you add some more logic. The a week later they find an edge case which needs accommodating, so you add a bit more logic to the function. Six months later you have a function with 10 parameters which is 100 lines long, and now before making a change to the logic you have to step through with the debugger for 15 minutes just to understand what the function is doing.
Clean code is the antidote to this disease. When a programmer follows these principles, they are always thinking, optimising, and refactoring their code. The goal is not clean code for the sake of clean code. The goal is to invest a little time and effort in the present to save a lot of time effort and confusion in the future. On his website Uncle Bob has the motto, “The only way to go fast, is to go well”.
Interestingly, even Facebook, which used to represent the antipathy of this concept with its famous motto “Move fast and break things” recently revised this to, “Move fast with stable infra”. Mark Zuckerberg explained in 2014 that “What we realised over time is that it wasn’t helping us to move faster because we had to slow down to fix these bugs and it wasn’t improving our speed”.
So by writing clean code, the coder is making sure that future productivity does not suffer. The fundamental concept to take on board is the “Boy Scout rule”. This rule states that Boy Scouts should “leave the campground cleaner than they found it”. Uncle Bob adapts this to programming and says that you should commit the code in a better state than when you checked it out. If every programmer makes sure to do this, then the code will be clean and easy to understand.
When writing code which is easy to understand, the names which are given to functions and variables are very important. It is worth taking a moment to think about a good and clear name when you are writing code. A good tip from Uncle Bob is that class names should be a noun phrase e.g Customer, whereas method names should be a verb phrase e.g Register. When the name of a class or method clearly explains what it does, then this also leads to a reduced need for comments.
Comments are often used to compensate for bad code. The code is confusing to understand, so the programmer writes some comments to explain what is happening. This is wrong, the code should be self-explanatory eliminating the need for these comments. The worst case scenario is when a function is changed, but the comment explaining the code is not changed, now the comment is completely confusing.
Another bad comment style is just using comments to comment out old code. This does not need to happen in a world with version control. We can just check out an earlier version of the code, so can delete the code rather than commenting it out.
Good comments are comments which explain the intent behind a piece of code, this can be especially useful to document an unusual request from the customer. Another valid reason for comments is the TODO comment.
A function is clean when it does only one thing, and does that thing well. This is encapsulated by Uncle Bob in the Single Responsibility Principle. This means that a function’s responsibility is clear, it is communicated by the name of the function and avoids side effects. Another good piece of advice when creating a function is to minimize the number of parameters to two or three. Passing in too many parameters can make a function more complex and harder to understand. If a function does more than one thing, is too long or complex or takes too many parameters, this is a sign that the function needs breaking up, either into smaller functions or into a class.
A programmer who cares about the code which they are writing will write clean code. If the programmer takes a slapdash approach and only aims to hack together a quick solution with no eye on the long term implications, their code will be messy and they will end up with an application which follows the big ball of mud pattern.