This post was originally posted on my blog at cvuorinen.net
What is Clean Code?
Clean code is subjective and every developer has a personal take on it. There are some ideas that are considered best practice and what constitutes as clean code within the industry and community, but there is no definitive distinction. And I don't think there ever will be.
After reading a few books on the topic, giving it some thought and delivering a couple of talks on the subject, if I had to summarize what clean code means in one sentence, I would say that for me:
Clean code is code that is easy to understand and easy to change.
Ok, that sounds nice, but what does it really mean? Let's break that sentence apart and examine the individual points behind it.
Easy to understand means the code is easy to read, whether that reader is the original author of the code or somebody else. It's meaning is clear so it minimizes the need for guesswork and possibility for misunderstandings. It is easy to understand on every level, specifically:
- It is easy to understand the execution flow of the entire application
- It is easy to understand how the different objects collaborate with each other
- It is easy to understand the role and responsibility of each class
- It is easy to understand what each method does
- It is easy to understand what is the purpose of each expression and variable
Easy to change means the code is easy to extend and refactor, and it's easy to fix bugs in the codebase. This can be achieved if the person making the changes understands the code and also feels confident that the changes introduced in the code do not break any existing functionality. For the code to be easy to change:
- Classes and methods are small and only have single responsibility
- Classes have clear and concise public APIs
- Classes and methods are predictable and work as expected
- The code is easily testable and has unit tests (or it is easy to write the tests)
- Tests are easy to understand and easy to change
I plan to write more posts later that cover these topics in more detail.
Why should you care about Clean Code?
As Robert C. Martin stated in his book Clean Code: A Handbook of Agile Software Craftsmanship, "Clean code is code that has been taken care of. Someone has taken the time to keep it simple and orderly. They have paid appropriate attention to details. They have cared." But why should you care? What's wrong with code that just works?
You should care because code is (almost) never written just once and then forgotten. Most of the time you, or someone else, need to work on the code. And to be able to work on it efficiently you need to understand the code.
And because people need to understand the code we write, we can say that the code we write is not intended only for the computer but also for humans.
Programming is the art of telling another human what one wants the computer to do.
– Donald Knuth
If you write clean code, then you are helping your future self and your co-workers. You are reducing the cost of maintenance of the application you are writing. You are making it easier to estimate the time needed for new features. You are making it easier to fix bugs. You are making it more enjoyable to work on the code for many years to come. Essentially you are making the life easier for everyone involved in the project.
Now, I'm not saying you should get obsessed about clean code. Your code needs to provide value, so you can't spend countless hours making it perfect. Clean code usually doesn't happen on first try anyway, so you need to adopt a mindset that you will always strive to improve the code you are working on. You then need to decide when it is good enough and move on.
Conclusion
In this post I have tried to explain what clean code means to me and also hopefully convinced you that you should also care about clean code (in case you didn't previously).
To close things up, I would like to share a few more of my favourite quotes and tweets I have come across lately.
If you want your code to be easy to write, make it easy to read
– Robert C. MartinClean code always looks like it was written by someone who cares. There is nothing obvious you can do to make it better.
– Michael Feathers
Beautiful code, like beautiful prose, is the result of many small decisions. The right method length here, the right object name there. – DHH (@dhh) March 21, 2014
"Code is like humor. When you *have* to explain it, it’s bad" - @housecor – About Programming (@abt_programming) March 24, 2014
“The cheapest time to refactor code is right now.” Great advices by @bugroll http://t.co/GGEQ8Bc3e1 #refactoring #cleancode – Luca Guidi (@jodosha) March 20, 2014
The cost of ownership for a program includes the time humans spend to understand it. Humans are costly, so optimize for understandability. – Mathias Verraes (@mathiasverraes) April 18, 2014
Dev time = 60% reading and 40% writing. Code refactor can reduce reading by 20%, improving 8 hours/week, or 416 hours/year. #refactor – Refactoring 101 (@refactoring101) April 7, 2014
Top comments (4)
The hardest here is to begin with the idea to make it easily understandable and finish with it because sometimes you lose the control in making it easy to understand and you only think about making it do what you want it to do
Any tips for a somewhat beginner, writing functions that tend to be way too long, re-using variables too often?
Learn to use the extract method refactoring to split long methods. Look for clues when to use it, like if you feel like you should write a comment to explain some operation. Sometimes when writing a new public method/function I first list what the method should do as 2-4 lower level operations and write these as comments. I then start implementing each step as a separate function. This is more rare though, as I said in the article, clean code rarely happens on the first try, so learn to refactor.
Regarding the variables, if you are working with a language that allows you to specify variables as read-only then use that as a default (e.g. use
constrather thatletorvarin javascript) and only allow mutability when needed (makes you more aware when this happens and why it's needed). Also, splitting long functions into smaller ones helps with this problem as well ;)Try to write functions so that it does one thing. If there are few steps that had to be done try splitting it into chunks and then extract those chunks into private functions to make it easier to read. When you extract your code to another function give it a meaningful name. Sometimes it is good to look at the function after 1-2 days to see if you still know what's going on. And refactor, refactor, refactor! Many programming IDEs has nice refactoring tools so take advantage of those.
When I write a function I start with each big step of the task it has and write it as a separate function call and then write the code of the function accordingly. It's a similar approach to Carl's comments. Sometimes it helps to start with paper, programming doesn't start with writing a code ;)