What is “Clean Code”?
The term comes from a famous book written by Robert C. Martin, or as he calls himself on Twit… X, Uncle Bob. He was involved in writing the Agile manifesto, a pivotal set of ideas that changed the way software was being develop. So in essence, Clean Code was a book explaining how code should be written to adapt and grow assuming an agile environment. This book was originally written in 2008 and the impact it had is so big that nowadays people use the term clean code in normal conversations… even if they didn’t read or know the book.
And what is the book about? It emphasized the importance of writing clean, readable, and maintainable code, and it introduced several principles and practices that have since become fundamental to modern software development.
The key techniques and principles it proposes are the following (thanks ChatGPT for summarizing these for me):
Readable Code: The book emphasized that code should be written for human readers, not just for the computer. It introduced the idea that code is read more often than it's written, and thus it should be easy to understand and follow.
Naming Conventions: "Clean Code" advocated for descriptive and meaningful names for variables, functions, classes, and other elements. This practice improved code readability and made it easier to understand the purpose of each piece of code.
Small Functions and Methods: The book encouraged breaking down code into small, focused functions and methods that do one thing well. This approach made code easier to understand, test, and maintain.
Comments and Documentation: Instead of relying heavily on comments to explain code, the book suggested that code should be self-explanatory through good naming and structure. While it didn't completely dismiss the need for comments, it emphasized that well-written code should reduce the need for excessive comments.
Code Smells and Refactoring: The book introduced the concept of "code smells," which are signs that code might be poorly structured or in need of improvement. It encouraged developers to regularly refactor their code to eliminate these smells and improve the overall quality of the codebase.
Testing and Test-Driven Development (TDD): "Clean Code" highlighted the importance of testing as a means to ensure code correctness and to maintain a reliable codebase. It introduced the concept of Test-Driven Development (TDD), where tests are written before the actual code, helping to drive the development process.
Dependency Management and SOLID Principles: The book introduced the SOLID principles (Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion), which provide guidelines for creating maintainable and flexible software architecture. These principles help developers design modular and loosely coupled code.
Coding Standards and Best Practices: "Clean Code" laid the foundation for many coding standards and best practices that are now commonly adopted in the industry. Its influence can be seen in style guides, code review processes, and development practices across different programming languages and communities.
So far so good. I read the book a few years ago, and it wasn’t so impactful for me precisely because the principles it explains were already known to me. Letting aside the fact that it uses Java as the language for showing examples in the book, and I personally don’t like Java too much (it is too much redundant for my taste), I recognized that if I had read the book when I started working as developer, it would’ve been a great lecture.
In any case, I am sure every developer, no matter their experience, has heard of at least one of these concepts. And it was a fundamental key in changing the industry.
However…
There has been conversations since years ago regarding the quality of software in the last decade. Not very public or visible conversations, but it was a seed that now has grown more and more. The gist of it is that, with the really powerful hardware in existence nowadays, it is surprising that software has not improved much in terms of efficiency. Just search software is bad on internet and you will see.
The opinion of those who consider software is bad and needs to improve is that compared to the programs that were developed in the 70s and 80s, with a very limited resources, forced the developers to be really good at it, thinking carefully how to implement algorithms and functions. On the other hand, modern software takes seconds to do some tasks, to start up and still has breaking bugs and defects that should not be there. And the users would become so used to it, that having bugs is expected. This comes back to early 2000s at leas, as we can read in this article from MIT.
In the last 15 years alone, software defects have wrecked a European satellite launch, delayed the opening of the hugely expensive Denver airport for a year, destroyed a NASA Mars mission, killed four marines in a helicopter crash, induced a U.S. Navy ship to destroy a civilian airliner, and shut down ambulance systems in London, leading to as many as 30 deaths.
This is something that is not happening is the automotive industry, or microprocessor or even airplane designs. Actually, the last terrible havok that happened with Boeing and its Boeing 737 MAX disaster was caused, in big part, due to bad software design.
Casey Murattori and Uncle Bob
Some time ago, Casey Murattori started a course for performance programming. The rationale behind it is that a lot of developers don’t know how code is converted into machine code, and eventually, they don’t know how to properly change the code to make it performant in execution. And he released this video as a part of the intro to the course. I strongly recommend you to watch it:
This unleashed some polemic and it even provoked Casey and Uncle Bob had a written discussion on Github. First of all, I would like to say that I loved that idea of having a discussion in writing using a git repository. But going back to the discussion, it is extremely interesting to see two great programmers, from different eras and points of view, discussing about deep concepts related to programming. There are many interesting bits of information. It takes time to read, but it is totally worth it.
But let’s just sum it up quickly: there are two positions in this debate related to Clean Code.
Casey’s position is that, if taken as an absolute way of writing software, clean code approach will generate bigger and complex structures, and code indirections, and as the problems to solve grow in complexity, it leads to quite inefficient software that just run fine because the hardware is powerful. But it harms the development of software as a whole and the efficient use of the hardware devices at our disposal. The focus is on saving processor cycles and avoid waste when possible, as rarely there are very clear and defined bottlenecks when it comes to bad efficient, as it is the general design of the code and software what hampers efficiency.
Uncle Bob´s is that clean code principles prioritize developer cycles over computer cycles, as he maintains the idea that computer cycles are cheap, developer cycles are not. Meaning that focusing on optimizing or writing efficient code as a priority, will be worst than following clean code ideas and patterns and only then trying to solve efficient bottlenecks.
You may be in one side or the other. In my case, I tend towards the side of Cassey. But I believe it is because that way of thinking, looking into low level details and learning about them is what always drove me. Is it that I think that is the correct way? To some degree I do, as I think developers nowadays (and I include myself) don’t know enough of how computers work at lower levels than the programming language they use. And that is a net negative for software as a whole.
I also believe software is way worse than it should or could be, and a big part of that is the lack of knowledge about how code is translated into executable code. It applies both to compiled languages and interpreted ones. But, is that the reason I will stop using the term Clean Code?
Nothing to do with Clean Code book or principles
When I read Clean Code I already had quite some experience in programming and I already had a solid grasp on many of the ideas in the book. Obviously it was due to its influence, meaning that I learnt that from other developers and from internet articles, papers and tutorials. So that says a lot about the influence its ideas had in the software industry. I also think the ideas were very important when it came out the first time, as it gathered methods tested in the industry during some years and presented them in a clear manner. Things like giving meaningful names to variables, now pretty obvious, was probably not so common at the time. Many developers then came from early eras of programming where you had to limit the length of your code, or you got used to short names.
And the discussion above notwithstanding, I think it was a very important book. Actually Uncle Bob is one of the author and signatory of Agile Manifesto, which also is fundamental.
However… both Agile Manifesto and Clean Code suffer the same problem for me. It became religion. And worst of all, not necessarily following the original content.
What do I mean by this? Have you ever read articles talking about clean code (without capital letters)? If you read carefully, when those articles talk about clean code, they don’t mean they follow this and that principle stated in the book. It became more of a intuitive feeling about the code being nice. Nice to read, or maybe nice to modify. Sometimes is nice as in “the logical structure is pleasant to my mind”. There are some of the principles that are always there, like SOLID principle. However the term clean code has been “corrupted” to a point where it is not really clear if the person using it is actually saying the code follow those principles or it is just the feeling that person has about the code in particular.
So who is right then?
No one? At least, no one is completely right. I believe software could be better and that developers should try to understand what is happening under the hood of their tools and languages of choice. We have a legion of programmers that just know how to use a framework (as ThePrimegean says, that is a mistake) or a high level language with no really understanding what they are actually doing. Just “connecting pipes” in the right order. And that creates the mess you can find in some environments like Android Apps, or webs taking forever to load. And that is a recipe for disaster, in my opinion.
On the other hand, learning lower level details is hard, takes time and we have to pay bills. So I understand that a developer decides there is no time for that. Mostly in highly changing sectors like the ones mentioned above, where you may need all that time to learn the new framework, the new changes in libraries, languages and new technologies that pop up every few years, management deadlines...
So both of them are right to some degree: knowing better how things work under the hood will help us make better software; but with so many companies in need of software and so many developers that are away from the low level details, Clean Code principles are needed. They help you create code that is way more maintainable and easier to evolve, without the need to find really good programming nerds that love the details of compilation, execution, memory, caches…
But still, will avoid using “clean code” expression
Because it became unclear. Every job posting requires you to write “clean code”, because HR department or head hunters are not technical in nature (mostly) and they heard that is great, but once in the job you find that they don’t really know or enforce the concept, but is more like an undefined concept that they don’t even know how to recognize. And the code base is not really Clean Code as Uncle Bob described in his book.
More or less the same problem when a company tells you they follow Agile practices… good luck with that, as every company takes Agile and adapts to its own ideas and you end up with a rigid structure following “ceremonies” (and that is the real name for it) even if they bring no value to the particular project itself, even hampering the work.
Because principles are that, principles. Meaning that you should consider them but only follow them if in your case, they are helpful. And Clean Code consists of very clearly defined concepts and ideas, but “clean code” does not.
So if you talk about Clean Code, use if with capital letters or don’t use it at all, because otherwise we have a concept that describes whatever each one thinks is “clean code”.
What do you think?