Is producing quality software art or craft? There are many books (see below) about writing clean code. And even more rules. The problem with having too many rules is that they tend to contradict each other. And some rules may not always be applicable and may make things worse depending on the situation.
Whenever I need to refactor, more often than not I find multiple ways of improving my code. The question is: which one shall I pick?
Is there a core set of rules that always apply and help in any situation? As in an 80/20 manner, where 20% of all the rules count for 80% of clean code?
I think there is. Following are my five candidates.
Top 5 most important traits of clean coders
5. Be stingy and only give what was asked for
Famous last words of projects: “I know the client only asked for requirement X but I made our framework generic so that with our next customer, if he asks for Y or Z, it can deliver that for free!” Yay…
Well, guess what: that next client never came. Instead, the existing client changed his mind and didn’t want X but X’. The generic solution was not prepared for that. And with the over-engineered solution, it was necessary to not only change X to X’ but also Y to Y’ and Z to Z’. And the task to solve X (and X’) become much more complicated and time-consuming.
A clean coder does not try to anticipate the future. He never over-delivers or surprises. What may be great customer service is bad programming advice. Trying to predict future requirements and “preparing for it” so that anticipated requirements can be “easily integrated” is one of the most frequent sources of unnecessary complexity.
Even if it is a hard thing to do, everything that is not needed has to get cut out.
A stingy developer is a refactor-maniac. As a consequence of not anticipating the future, it is necessary to refactor constantly. And that is a good thing. Because it means that it is not the developer who decides what the software should do but the users and clients.
4. Have a one-tracked mind and only worry about doing that one thing
Every method/function/class of a program should do only one thing. And only that one. The one-tracked mind developer only thinks about what that one purpose is a function or method should do.
If every unit of a program does one thing only the overall architecture will layout itself. This is not something that one gets right the first time (at least not me).
Doing one thing also means one level of abstraction. When a problem gets solved neatly by divide-and-conquer 1, the level on which the problem gets solved should be the same for the method.
Sticking to this rule has following effects:
- it keeps functions and classes short. As each part does only one thing it can not be anything else than short.
- it minimizes side effects. This one thing includes of course hidden effects.
- it minimizes surprises. Again one thing and nothing else. No surprises.
3. Be self-centered and egotistical and refuse to be interested in other things outside yourself.
“I don’t want to know”.
Your colleague wants to explain to you all the nice intrinsics of his wonderful class so you can use and enjoy its full potential? Stop him before he starts blabbering and tells him “I don’t want to know”.
A clean coder is not sympathetic. The less she has to know about your code the happier she is. She is only interested in her own code and if your piece of software requires a lot of additional knowledge she gets grumpy.
And of course, this applies the other way round also. The clean coder loathes having to explain how his code works so he will make things as easy as possible for his fellow programmer. The perfect solution is one that is completely obvious and doesn’t require additional explanations.
The effects of this rule are:
- reduced dependencies, as each dependency means something I have to explain the user of my class.
- similarly, higher modularity/independence, as the least I need to know the easier I can incorporate a class, module, method.
- fewer side effects, the evilest type of required knowledge.
- encapsulation/information hiding, which is basically just a nicer way of expressing this rule.
2. Be the shortest lipped person on earth and never repeat yourself
Oh, you know those people. They can never shut up. They tell you over and over again the old stories. Sometimes they come up with an apparently new story but at the end it is same, you have heard all it before.
It’s the all-time classic DRY: Don’t repeat yourself.
Just following this rule, if taken to it’s fullest, can get one very far. There are the obvious cases of plain code duplication, but it can go much further than this. If for example, if we notice in our framework that a similar thing has to be many times, something is wrong.
It is the extension of doing only one thing. My functions may do only one thing but they all may do similar things and should be refactored.
And similarly, DRY + one thing only will lead to a clean architecture. It has to.
By the way: this does not mean to write less code. Quite the opposite, doing only one thing + not repeating functionality often requires writing more code.
1. Have the attention span of a fly and keep all you do stupidly simple
That’s the winner. If my code is so simple that with one glance I can grasp it everyone wins. Even if it is buggy or un-efficient anyone can fix it as it is so simple to understand what it does.
Dead simple code is the result of all the previous rules. It means that a problem has been understood so deeply that we managed to break it down into it’s most basic parts.
Simplicity is elegant. Yes, I may hack my 50 lines of code into one complex beast of a regular expression but then I’m also the only person in the room who understands it. And don’t ask me in one month later for changes. Because by then I will have forgotten most of how I came up with my hack.
Ok, so you might say: “I just keep things simple and I’m done, great advice”. Of course, it’s not that easy, in fact, it is most difficult. That is because software development still is partly art and partly craft. But applying the clean code rules and refactoring/fighting for simplicity every day will get us there.
Simplicity is the most important factor that determines the productivity of the development team. It’s opposite, the mess, that lets cost explode and puts projects to rest.
Resources
Some books I found useful:
- Clean Code and Clean Coder by Martin (probably the most complete list of rules)
- Effective Java by Bloch (if you happen to be a Java developer, this is still my bible).
- Refactoring by Fowler
- Code simplicity by Kanat-Alexander (more aimed at management)
- Code complete by McConnel and The pragmatic programmer by Hunt (talking about more than clean code)
I also recommend pretty much all talks of Rich Hickey, even though they are tackling a rather high-level view of software quality.