The Golden Rule of Clean Code
Ever since I started programming, I’ve always been passionate about writing clean code. I’ve learnt to appreciate that writing working code was only a small part of my job; writing readable and maintainable code was much more important.
I’ve been wanting to write a blog post about clean code for some time but I felt like there’s already plenty of those blogs out there and I didn’t want to repeat the same message.
I recently watched a talk by Uncle Bob on clean code and some of the things that he said really blew me away. In particular he mentioned something that I hadn’t heard before and therefore I think it’s worth sharing. I believe that what he mentioned is the golden rule of clean code.
Now, I’m not saying that if you follow this rule your code will be as clean as it could be. Instead I believe that just by following this simple rule, your code will adhere to most clean code principles and it’ll be much more readable and maintainable.
What is the rule?
The basis of the rule is extremely simple, and one I had heard many times:
I’m sure this is not ground-breaking and it’s something we’ve all heard before, but what Uncle Bob said next is what changed the game:
A function does one thing if you cannot meaningfully extract another function from it.
I’ve heard various explanations for what one thing was, none of which were as clear and impactful as this one.
Now meaningfully is still subjective, and in some way I believe that is intentional; programming is an art and there must be some freedom in it. However, Uncle Bob does provide a further explanation which might add some more clarity and make it a bit more objective:
A block of code can be meaningfully extracted if you can give it a name that is not merely a restatement of it’s implementation.
With all of that said, here is what I believe to be The Golden Rule of Clean Code.
A function should not be able to have another function meaningfully extracted from it.
What makes this the golden rule?
It’s easy to implement
Extracting functions is one of the first refactoring tricks we are taught as programmers. It’s also, one of the easiest refactoring tools in our arsenal. Everyone knows how to extract a function. It’s so easy that even an IDE can do it.
It’s easy to follow
If you read clean code blogs you’ll see they’ll list out many different rules to follow. Whilst they’re very clear and specific, they can sometimes be hard to remember and thus harder to follow.
On the other hand, this is one simple rule. By just following this rule, your code will be much cleaner and easier to read; your colleagues and your future-self will thank you for it.
It makes your code clean
If you implement this simple rule, your code will adhere to most clean code principles. Below is a list of the classic clean code principles you’ll read about followed by an explanation of how the golden rule would make your code automatically adhere to them.
- Keep functions short
If your function cannot have another function meaningfully extracted from it, it’ll be short. - Avoid too much indentation (arrow code)
If you’re extracting functions as much as you can, you’ll find that your functions will have a small amount of indentation (1 or 2 at most). - Don’t Repeat Yourself (DRY)
We’ve heard this one many times before. The beautiful thing about the golden rule is that if you follow it, you’ll be able to more easily identify the duplication in your code and consequently find the right abstraction point for code reuse. - Avoid mixing high level concepts with low level concerns
Long functions tend to go from high level concepts to low level concerns. If you’re extracting functions, you’ll see that also your high and low level code will be separated. When this happens, your code will start to read like a newspaper article, and your readers will be able to traverse your code as shallow or as deep as they’d like. - Avoid comments (unless strictly necessary)
This might be a controversial one and I don’t want to get into that in this blog but it’s certainly something Uncle Bob is very clear about (he has a dedicated talk about it).
Thankfully, following this rule will allow your code to explain itself. The reason for this is that functions have a beautiful characteristic that they provide metadata to a block of code. This metadata is the function’s signature (inputs and outputs), the function’s name and it’s location (namespace, module, etc).
With this metadata throughout your code, you’ll find that your code will explain itself and the need to write comments will diminish. - Use meaningful names
To explain how the golden rule helps to follow this clean code principle, I’ll need to use Uncle Bob’s explanation of this principle and how it is related to the scope.
A variable name should be proportional to the size of the scope that contains it. Following the golden rule will help reduce the scope of variables as much as possible which will in turn lesson the need for longer variable names.
A class/function name should be inversely proportional to the size of the scope that contains it. Following the golden rule will mean that each class/function will do a very specific thing and the scope will decrease as you extract. You’ll need to name the extracted classes/functions appropriately and this will lead to more descriptive names as the scope decreases.
It primes your code for further cleaning
As I said at the start of this blog, this rule is unfortunately not a silver bullet. It’ll do a great job at cleaning your code, but it does not always guarantee the final state is as clean as possible. However, what it will do, is leave your code in a state that is primed for further cleaning.
Splitting your code out into these small functions will allow you to see abstractions that you wouldn’t have seen before. Furthermore, it’ll allow you to see variables whose scope could be decreased, lowering the cognitive load on readers. Moreover, having the ability to focus on one small code block at a time will allow you to find more readable and clever ways to write it.
It makes your code testable
Writing tests for the code that we write is paramount. Uncle Bob makes an interesting point in his talk on TDD where he likens the writing of tests to double entry bookkeeping.
However, writing tests for long functions can be extremely difficult. You can find yourself wanting to test one part of the function, but needing to set everything up (even unrelated things) so that the unit under test (the long function) executes to completion.
When you split that long function into many small functions, you’ll find that writing tests will be much easier and pleasant. The tests will be smaller, more specific and targeted.
You’ll find that a lot of these smaller functions will be pure (no side effects) and pure functions are extremely easy to write tests for because you’re just setting up a set of inputs with their respective expected output.
Concluding thoughts
Writing clean code is much easier than we thought. We can do so by taking a simple refactoring tool that we have all been taught (extracting a function) and using it in every function we write; using it till you cannot meaningfully extract another function out of it.
This simple process will make your code much more readable, maintainable, testable and easier to reason about.
I hope you can join me and start implementing this simple rule and extract our way to cleaner code.
