«Clean Code» and a clean cat
There is nothing developers enjoy better than arguing about clean code: Dan Abramov, for example, has recently fueled the hype with his blog post, «Goodbye, Clean Code».
However, “clean code” per se doesn’t even have a clear definition. The main book on the subject is Clean Code, where Robert «Uncle Bob» Martin states that there are perhaps as many definitions as there are programmers. But he doesn’t walk away from the fact with a conclusion that there’s no reason to discuss clean code, rather — compare several definitions and highlight general ideas. Therefore he cites the views of several outstanding programmers on what clean code is.
So we have also become interested in what people in 2020 think of clean code. Have the views changed since the publication of the book? Do opinions vary in different IT fields (maybe backend developers perceive the idea of clean code differently from testers)?
We've already published the results in Russian, and here's the English version. Since the topic is known to provoke discussions, feel free to give your own definition or argue about those already given!
UPD: When we posted this article, Uncle Bob had our conferences in his schedule. Unfortunately, the situation has changed. We updated this post on March 12, to avoid any misunderstanding.
Jon is a Stack Overflow legend, author of C# in Depth, and one of the world’s most famous dot-Netters. Here's what he told us:
«To me, clean code is boring code, in the implementation. There are no surprises, other than how unsurprising it all is. I should be able to feel „Yeah, I could have written that” even if I couldn't — because it's designed so well.
With the right abstraction, the implementation can fall out naturally. Ideally, that abstraction should feel simple and obvious too — even though in reality, getting it to that state can take hours, weeks, months of consideration and experimentation.
The lack of surprise then propagates to the use, as well — when I write code against a well-designed API, my code becomes obvious and boring too.»
For those regular attendees of DotNext, Andrey needs no introduction. But for those who don't know, he’s known for his work on Rider (.NET IDE) and BenchmarkDotNet (a benchmarking library), his fantastic talks, and his book Pro .NET Benchmarking.
When asked about his opinion on clean code, Andrey referred to two of his old blog posts: «Perfect code and real projects» and «To Add Comments or Not to Add?». For those of you who don’t have time to peruse two articles, we took a couple of paragraphs from there:
«I like perfect code. This is not only the correct way to develop applications but also the real proficiency. I enjoy reading a good listing not less than reading a good book. Developing architecture of a big project is no simpler than designing architecture of a big building. In case the work is good the result is no less beautiful. I am sometimes fascinated by how elegantly the patterns are entwined in the perfect software system. I am delighted by the attention to details when every method is so simple and understandable that can be a classic sample of the perfect code.
But, unfortunately, this splendor is ruined by stern reality and real projects. If we talk about production project, users don’t care how beautiful your code is and how wonderful your architecture is, they care to have a properly working project. But I still think that in any case you need to strive for writing good code, but without getting stuck on this idea.»
The DotNext crowd may remember Dylan both from from his thoughtful and vivid talks (for example, the one about working with legacy code) and from his parody songs. When we asked Dylan to comment on clean code, he came up with this detailed reply, which seems like it deserves a post of his own:
«What’s interesting to me is how that phrase „clean code” has taken on a currency far beyond the scope of people who have read the Robert Martin's book. I've talked to many, many developers who have heard the phrase „clean code” but haven't read the book. I've even seen it crop up in code reviews — „this is all pretty good, but could you clean it up a bit?” — which can be infuriatingly imprecise if you're not sure what «clean» means in that particular context.
You see, we have all these words in English that often crop up together — „clean”, „tidy”, „organised”, „neat” — and as a native English speaker, to me, they all mean subtly different things. I think there's value in exploring some of the connotations of those words as they can be applied to software development. Imagine, say, a restaurant kitchen. The word „сlean” has very specific connotations in that context. Everything's been washed, the utensils are sterilised, there's no danger of cross-contamination from uncooked food or anything. But that doesn't necessarily mean it's very well organised. If you've ever tried cooking dinner at a friend's house, or in the kitchen at your Airbnb, you'll know how infuriating it is when things aren't in the right place. There's washing-up liquid in the cupboard where you expect to find saucepans, you can't find the garlic press — you know. Everything's clean, sure — there’s no danger that anybody's going to get sick eating food prepared in that kitchen — but it's a frustrating place to work.
Now think about a woodworking shop. That's also an environment where dirt, grease and contaminants can cause problems, but you're working with a very different definition of „cleanliness” than you'll find in a restaurant kitchen. You can clean a woodworking chisel until it positively shines, but you still wouldn't use it to cut up sausages. So this word „clean” can be a very subjective term.
But to me, words like „tidy” and „organised” work across contexts where „clean” doesn't necessarily translate. „Organised” means somebody's put serious thought into how to arrange elements of that particular workspace, and „tidy” means that those elements are all in their intended places. Like the old saying has it, „a place for everything, and everything in its place”.
Maybe we can think about code in terms of being clean, being tidy, and being organised — as three distinct things. Clean means that you look at the constituent elements of a codebase — methods, functions, interfaces — and don't find any cause for concern. Naming conventions are respected; variable and method names are spelled correctly; details like indentation and brace style are consistent; everywhere you look you find reassurance that, at the most basic level, this workspace is operated by people who take this stuff seriously. It’s the opposite of „dirty code” — code that’s full of spelling mistakes, inconsistent brace styles and indentation, mismatched filenames. The kind of things that get magically fixed when you run the ‘code cleanup’ tool in something like ReSharper.
Organised is about architecture. It's about being able to dive into an unfamiliar codebase and find things where you expect them. Interfaces and domain boundaries are a help, not a hindrance; methods and variables aren't just correctly spelled and formatted, but they reflect the ubiquitous language of the stakeholders and business operations you're working with.
And tidy is about respecting local conventions… a codebase where you can find the things you need, in the places they're supposed to be, even if that particular organisational model doesn't make a whole lot of sense to you at that exact moment.
I think the „clean code” movement is actually a shorthand for all three — but, particularly when you're working on complex legacy codebases, going for fully „clean code” can be a pretty daunting prospect. Perhaps there's mileage for all of us in digging a little deeper and working out what it is that can really make a difference to the thing we're working on right now.»
It's a «conference about testing, not just for testers». So Heisenbug is at the intersection of development and testing, and most of its speakers have a good understanding of both those fields.
Ivan Krutov and Anna Chernysheva
Ivan and Anna work at different companies, but they both know a lot about Selenium. We talked to them at the same time, so we got a joint definition:
Ivan: «For me, the simplest definition of clean code is the code that is understandable without the need for comments, it sort of documents itself. Code that is littered with comments is not pure code.»
Anna: «For me it’s kind of the same thing: clean code is code which you can figure out quickly and that doesn’t result in bugs, which can be easily extended.»
Ivan: «I can also add that clean code is code you’re not ashamed of. There’s also a saying that if you look at the code you wrote six months ago and you are not terrified, then it means you’re not professional growing. That basically means that with each new coming year your code must become cleaner.»
Sebastian is the Lead Java Developer Advocate at IBM. You can meet him at the Java conferences, but since this time he's coming to Heisenbug, we specifically asked him about clean code in relation to testing, and this is what he had to say:
«From my experience having proper code quality is not only important for our production code, but also for our tests. In our tests, clean code, proper abstraction, and delegation is often underappreciated, which results in unmaintainable test code. Once we refactor production code, or have to adapt its behavior, it shows whether we did a good job in modeling and implementing our tests.»
Andrey is working on the browser autonation tool Playwright, which we recently covered. His definition turned out to be the most concise:
«Clean code is dumb and very clear. And the dumber the better.»
Alexandra is an application security expert in OK.RU who started her career in IT as a Java developer, but then became interested in security. She told us:
«Clean code has three distinct traits: another developer can read and understand it easily; small modification require proportional effort; you can predict the effect of any specific change.
What this means in practice is that code is structured, concise, follows best practices for the language it is written in, doesn't have implicit dependencies and is covered with tests.»
Andrey is known to many Russian readers for the project devSchacht. It is not surprising that a person who constantly formulates his thoughts in a podcast formulated his position quite clearly:
«In his three main books (Clean Code, The Clean Coder, and Clean Architecture) Robert 'Uncle Bob' Martin tries to answer the „who, what and how” of writing code.
We can argue about the correctness of some of his conclusions, but something that’s definitely indisputable is that all those books are based on prolific personal experience and just, well, common sense.
And within the same framework, I can just add that clean code, for me, is code that is written by a person who stumbled over a considerable number of pitfalls in his programming life and during this painful process learned to how all of those pitfalls could be avoided gracefully.
You may not be comfortable with the style of this person, but if you follow it, you will arrive at the same thing.
You may take this style and recycle it, make it convenient for yourself. Or, otherwise, you can take it and rewrite it as you’d like making your own mistakes, and trying to come up with your own style, while everyone else will be looking at you in disbelief and just move forward under the mentorship of their older peers.
In any case, clean code is the code that is easy to read, easy to maintain and extend. These very attributes lay a solid foundation for apps that would live and thrive for years regardless of the external circumstances.»
Alexandra is member of the HolyJS Program Committee, she has 10 years of experience in programming — and, even though she's not a Heisenbug speaker, she also knows a lot about the testing (unit, integration, E2E, B2B). Here's what she told us:
«Clean code is a simple concept, but it's not easy to grasp it. I think that code can be clean if it follows these rules:
— every separate piece of code should be able to scale or grow/evolve independently of other pieces, while maintaining the original idea/integration with other pieces (SOLID helps a lot with this, as well as the rule «decisions should be made as late as possible).
— code should feel like an exciting book with clear and typical names. To make a comparison, if you would write a short story, you would probably give it a typical structure with the setup, climax and resolution. Even if you're the only one working with the project, code should be easily read by yourself anytime later, regardless of the architecture, language and frameworks.
— code should have a clear structure: the reason any piece of code is present should be obvious.
— every line of code should be motivated by business goals».
Nicolò is a core Babel developer and a mathematics student — and manages to fit in giving talks on conferences. Here's his take on clean code:
«Clean code is code that can be easily divided into small atomic units.
An „atom of code“ is the smallest possible set of instructions which make sense of their own, without too much reliance on the surrounding context: variables and operations names should be descriptive enough that who is reading them don't need to allocate additional memory in their brain to store their definition and their possible modifications, and it doesn't require to look somewhere else in the code to understand what the result of the „atom“ means. The smaller the atoms are, the easier it is to understand what the code does.
Code can be clean regardless of the programming language or paradigm used: atoms can be implemented as small objects, functions, or even as small pieces of code not isolated from a syntactic point of view.»
After we got all those opinions, we showed them to Uncle Bob himself, and that's what he told us:
«I enthusiastically agree with all the previous commenters. I would only add one thing. It’s something that Michael Feathers said. “Clean Code always looks like it was written by someone who cares”.»
His words sound very friendly. But the topic itself is so discussion-provoking that we're sure: while some of you are nodding in approval, some are burning inside thinking something like ths:
- «Oh come on! Akinshin says that the users don't care about the beauty of code and only about the project working great. But the „Clean Code“ book clearly states that clean code not only does look great, but has very pragmatic benefits: if the code is messy and dirty, development of new features slows down dramatically. So the whole purpose of clean code is to make the project good and the users happy!»
- «What „clear and dumb code“ are you talking about? I have no objections to it being clear, but naming things is an art form that requires a lot of thinking, how dare you use the word „dumb“ for result of such work!»
- «The words „making your own mistakes while everyone else will be looking at you in disbelief“ sound harsh. But the best and most innovative things in the world come from people learning from their mistakes and not just following some old book!»
It's interesting to know what objections arise, so feel free to state your opinion in the comments (just don't get personal).