Cover photo by Dan Wayman on Unsplash
Last week, Dan Abramov posted a very personal and humbling blog post entitled Goodbye, Clean Code.
I saw a tweet about this in my timeline and, being a long-term proponent of “clean” code, TDD and things of that ilk, I was naturally concerned. Here’s what I replied with.
I dislike Twitter because it’s so hard to find any nuance to arguments. So in this post I’ll explain what I mean by human code.
It’s easier to blame code than it is ourselves
I think it’s wonderful that Dan is blogging about deeply personal experiences in his career.
Many programmers who become team leads will have had a similar experience to the one he is describing. That time when your colleague wrote some code that you didn’t like so you rewrote it, because you wanted your codebase to be the best it could possible be. Then all hell broke loose. You offended your colleague, you made it awkward for the rest of the team, and your boss had to step in and sort it out.
At some point it dawns on you that being a team lead means leading from the back. That your team will only ever go as fast as the slowest person on your team, and your job is to help everyone level-up, not just yourself.
There were a bunch of people who replied to Dan’s tweet about his blog post with the same comment. Isn’t it interesting how common this experience is in tech?
Human code
We are getting to the crux of what I mean by human code. It is code that has been written with a people first approach.
I am unsure who first said the following expression, but I first heard it at the SoCraTes 2019 unconference. (Please let me know who said this, if you know!)
The two hardest problems in computer science are people, and convincing people that people are the hardest problem in computer science.
Isn’t that a wonderful saying? In my work as a software consultant helping businesses solve their software problems, almost always the biggest problem I see is interpersonal issues that stem from disagreements about project direction and structure.
Clever code
Another problem here is what does “clean” mean? It does not mean the shortest code, or the code with the most intelligent abstraction.
Take the acronym DRY (Don’t Repeat Yourself), which people misunderstand all the time, and then invent other acronyms like WET or AHA. We don’t need these acronyms. DRY is fine. It’s a topic that deserves a whole blog post on its own, but for now let me just say that there’s another term that helps understand the issue.
It’s the term clever code. I like this term because it brings to mind the image of the lone wolf, “10x” coder who is trying to prove themselves better than everyone else around them. This behavior is toxic. Clever code is toxic because it takes a disproportionate amount of time to read and maintain it. Clever code is a ticking time bomb.
And by the way, there’s no judgement here from me, because clever code is my default mode when I’m working alone. But I write much better code when I’m pairing with people. Working with others is a great way to block clever code from ever appearing.
So that is where the idea of clean code over clever code comes from.
But...
Clean code is dirty code!
Many of us in the software crafters community decided long ago to stop using the word “clean” to describe our code.
The problem is that by saying “clean” we are implicitly stating that some code is “dirty”. This can be very shaming for people. Particularly for beginners, it’s an example of the kind of word that leads to imposter syndrome, and a feeling that your code just isn’t code enough.
If you’re following the principle of human code then you want to avoid anything that could possible trigger negative responses in your colleagues, and that includes using the word clean.
It was Tobias Goeschel who first introduced me to the term clear code as an improvement on clean code. When I discussed this post with him, he reminded me that there’s a further problem with clean, and that’s the illusory binary distinction of clean vs dirty. All the code we write involves trade offs, and it’s not helpful to believe that there is always one right way of doing things.
Just like how DRY code isn’t a binary thing either. People hate on DRY because they believe it is a binary thing—it’s either DRY or it isn’t—but in reality DRY is just a gentle nudge in the right direction of code quality.
Yes, I care about code quality. But I also care about people.
Let’s stop judging each other. Let’s work together to create awesome software. 🤗
Latest comments (49)
I really want clean code but the company pays me for results. I clean my code when I can and study the concepts as much as I can to try and keep it in mind but it is not the law that pushes me around. I agree I never feel it is clean enough but I sometimes just have to move on.
I love the idea of human code.
I was once contributing to a project mostly written as clever code. Not so clever after all. It was very hard to understand all the bits and bytes. Hence, let's focus on the people!
Thanks for sharing your thoughts, Daniel
This post is strongly on point and awesome. Permit me to repurpose it has an audio-visual content and you will be credited for the job well done. Am I permitted?
Thanks in advance.
Send me a direct message and we can discuss it. Thanks.
More money is spent on maintaining software than on writing new systems.
It is more expensive to write and deploy crappy code than it is to write and deploy code that is "good" code. "good" depends on the context. But you have to write code knowing that someone else will be reading and understanding and changing it in the future. That's where most of the costs lie.
What you're generally talking about is the field of software engineering That is (IMNSHO), the coding implementation is just one part of the process of producing a part of an entire system that works correctly, is robust (handles failures appropriately), and is maintainable. Furthermore, the implementation happens in a context where time and resources cost money.
If you expect that the system you're working on will generally be thrown away in about a year, then the cost of doing line-by-line code reviews so that everyone on the team agrees and works to a particular standard is going to be much less than a system that you want to survive for a number of years.
If you are working on an airplane guidance system then the cost/benefit of code reviews is much different. Not only does your code have to be absolutely correct, when (not 'if') someone needs to change your code, it better be straightforward to make changes and not be so convoluted and brittle that any change will break it.
IOW, context matters. The cost/benefit analysis should guide you to what level of what standards are needed. Sometimes line-by-line code reviews are totally worth it and required. Sometimes they're not.
Version 1.0 of a system is much easier than version 3.5: in version 3.5 you have to deal with all of the mistakes that were made in all of the previous versions and all of the things learned since then and all of the changes in the world/business/area that have happened since then.
People have been thinking about and studying this and writing about this for decades. When developers start to grasp this, they have taken the first step to moving from "coders" to "software engineers."
I’m not sure if you’re comment is directed specifically at me (the author), but just in case it is:
The quote I’m talking about is not the infamous one you’ve given an attribution for. I’m talking about the variant which speaks to the larger of our industry’s problems today--i.e., people. One of the reasons this quote is magical is because it shows how outdated the original is.
Software engineering principles are generally not a match for today’s programmers given the industries they work in. If you haven’t already, I suggest you read Software Craftsmanship by Pete McBreen which will make clear some of the advances in thinking about software development in the last 25 years or so.
My point with this article is two-fold:
You're right -- I haven't read Software Craftmanship yet. But now I will.
But I also think that maybe my definition of "Software Engineering" is more expansive. My view of Software Engineering includes people and their behaviors and wants and needs and humanness as a major part.
Teamwork is a critical part of pretty much every software engineering process. And so if the leader of a team is not a good manager or leader, that negatively impacts that part of the process. If the leader of a development team isn't able to determine what level of code review is appropriate -- if the leader is insisting on line-by-line reviews with very rigid rubrics and that is not appropriate, then that will negatively impact the team and the code developed. That is all part of the software engineering process.
So I totally agree with you that
because that is part of software engineering. Everything involved in producing and deploying software -- whether it's writing it new from scratch or working with code that someone else wrote 5 days ago or 5 weeks ago or 5 years or 15 years... -- is part of software engineering to me. It's not just about writing code -- it's much larger than that.
Writing clean code is just one part.
And people are always part of the process. (developers, users, stakeholders, investors, ...)
The key is to be pragmatic about writing clean code.
Generally I ask myself 'if I, or someone with the domain knowledge, comes back to this code in 3 months time will we understand it?' If the answer is yes than probably the code is clean (clear) in the true sense.
Sometimes we have to accept some duplication in favour of readability, but then I tend to equate clean code to readable code reflecting the language of the business it is built for so maybe I'm biased :-)
It seems to me that Dan Abramov wrote exactly what you did. Maybe he used different "poetry" but the "findings" are the same (to me).
I agree with your approach which involves those two steps. But I do the refactoring if there are enough time to do so. Currently I work alone on both front-end and back-end in a project that has a lot of modules; sometimes there aren't enough time to refactor certain codes in my project.
I don't know ho said it, but "everybody can write code that a computer can understand, the hard thing is to write code that other developers can understand". :)
I think this is a vital message really.
It's much too easy to get bogged down in some sort of perfection mode, when your job is really to solve a problem in a usable way. I have had peers who spent weeks refactoring and rewriting code to solve a problem or add a feature, which should have taken a few hours to complete. They got stuck in making it perfect in their minds.
You might even call it premature optimization. You still need to keep good practice in mind as you are working, since you don't want to make your life difficult later, but there is no way you can know how to make it perfectly "clean", until you are further along in the process. Spending too much time on perfection early on, is pretty much YAGNI.
I'm old school, I really think the simplicity of "make it work, make it right, make it fast" gives you the best of both worlds.
If you avoid the pedantic need to make is perfect the first time, or make your teams code all conform to your clean ideal (which is pretty much an impossible task), then you will also cause much less friction, because every good team refactors each others code, as they come across it, but rewriting all that code is not a team exercise. You might as well be doing it yourself. You lone wolf you.
Human Code > Clear/Semantic code > Clever code > Dirty codeI like that. I guess I personally go from "clever" to "human", depending on the situation. Most often in the middle ground.