Writing code that is readable and understandable is a common-sense principle for many developers. However, in practice, the fundamentals of Clean Code are not always consistently applied.
1. Clean Code: What Are We Talking About?
Despite its buzzword status, Clean Code is not a new concept. Its origins can be traced back to Robert C. Martin’s book, Clean Code: A Handbook of Agile Software Craftsmanship, published in 2008. This book remains a key reference for developers and anyone interested in software development, as it emphasizes the importance of code quality and readability.
While many agree on the value of an approach that promotes quality and readability in code, implementing it consistently in daily practice can be challenging. That’s why it’s important to revisit the fundamentals and key benefits of Clean Code, along with some practical tips.
Definition Attempt
Before diving into the details, let’s start with a basic reminder: Why do we code? As Aurélien Castellarnau, Tech Lead at Wemanity, humorously points out, it’s certainly not “for the sake of art.” Behind every development effort is the intention to automate business actions. In other words, coding is always done with a business purpose in mind. The code written by developers should therefore make sense not only to machines but, more importantly, to all the humans who will need to read it.
With this foundational idea in mind, a simple definition can be outlined: “Clean Code is code that is easy to understand and read.” However, Clean Code practices go further by aiming to write code that is also easy to maintain. For Robert C. Martin, also known as Uncle Bob, 50% of a developer’s job is to make the code work. The remaining 50%? Developers spend this time, as our expert explains, “reworking functional code to make it more expressive for a human reader.” This less visible, almost thankless aspect of a developer’s job is essential, as it allows the code to endure over time.
“Clean code must be understandable and intuitive for all humans who will need to read it.”
Principles as Inspiration
The principles outlined in Robert C. Martin’s seminal work are not presented as strict rules or dogma. Instead, they serve as guidelines “to ensure that code is written with future collaborators in mind.”
Some of the key principles include:
- Keep It Simple and Stupid (KISS): Aims to minimise accidental complexity, which can hinder future development, as opposed to the necessary complexity required to solve a problem.
- You Ain’t Gonna Need It (YAGNI): Advises programmers not to add functionality to software until it is absolutely necessary.
- Don’t Repeat Yourself (DRY): Encourages avoiding code redundancy within the same application to facilitate maintenance, testing, debugging, and updates.
- SOLID principles: An acronym representing five design principles that help create architectures with a good level of decoupling between different logical units.
- Single Level of Abstraction (SLA): Emphasises maintaining the same level of abstraction for each line within a function.
Additional principles include:
- Following recognized conventions to create the most universal code possible.
- Leaving the code cleaner than you found it, following the “Boy Scout Rule” or “Leave No Trace” rule.
- Adhering to fundamental design and naming rules to help new developers understand the terminology and jargon used and facilitate meaningful discussions with business representatives.
- Creating short functions with a single purpose, no side effects, and as few arguments as possible.
- Writing clear and concise comments, avoiding redundancy and unnecessary noise.
- Structuring source code with proper indentation, variable declarations, and consistent structural formatting.
All the conventions of Clean Code can be found here: https://github.com/SAP/styleguides/blob/main/clean-abap/CleanABAP.md
Sometimes, even with the best intentions, parts of the code may escape the “spring cleaning.” Fortunately, Robert C. Martin provides insights on how to identify code that isn’t clean enough, which he calls “code smells.” Code smells are:
- Rigid, making them difficult to evolve.
- Fragile, leading to numerous dysfunctions.
- Immobile, making them difficult or even impossible to reuse for other projects.
- Unnecessarily complex.
- Repetitive.
- Opaque.
Developer: A Craftsman’s Job
Our discussion would be incomplete without placing Robert C. Martin’s work and Clean Code within the broader movement of software craftsmanship. Emerging in the late 2000s, this movement seeks to gather best practices to help developers write clean and appropriate code. Initially, software craftsmanship was simply a manifesto centered around four core principles:
- Not only working software but also well-crafted software.
- Not only responding to change but also steadily adding value.
- Not only individuals and interactions but also a community of professionals.
- Not only customer collaboration but also productive partnerships.
The goal of software craftsmanship? To defend the idea that well-crafted software is always better than software that merely works!
2. Clean Code: What Are the Fundamentals?
Quality Over Quantity
This idea is not always easy to embrace from the perspective of a sponsor or client. For them, constraints may lead to an emphasis on development speed, which can clash with the Clean Code approach. As Uncle Bob likes to say, “Developing fast means developing well.” It’s easy to see why some stakeholders view the Clean Code paradigm as a constraint or an obstacle to rapid software delivery. But Aurélien Castellarnau warns, “Beware of this false belief! Quick delivery will soon turn into technical debt, faster than you might think.”
Therefore, it’s important not to confuse speed with haste or prioritize speed over quality. Quality should always take precedence over quantity. “Keep It Simple and Stupid” (KISS) and “Don’t Repeat Yourself” (DRY) are principles that invite us to avoid over-engineering or writing code that isn’t immediately necessary. Common sense? Not always. When faced with complex problems, it’s tempting to anticipate future needs by writing code that might be useful someday or to “over-engineer” a solution. These are traps that must be avoided.
“Beware of this false belief! Quick delivery will soon turn into technical debt, faster than you might think.”
Test Before Coding
How? By adopting a test-driven development (TDD) approach, for example. TDD encourages developers “to let the code emerge through tests, step by step, line by line.” This iterative and incremental technique involves a series of back-and-forths between testing and coding. As Aurélien Castellarnau explains, “The goal is not to write inherently clean code but the necessary code without adding unnecessary extras.” This approach allows developers to focus less on the “how” and more on the “why,” less on the implementation of the solution and more on the need.
The tests should be fast, independent, useful, repeatable, and easy to run. They can be combined with two other methodologies:
- Behavior Driven Development (BDD): A scenario-based approach that aims to avoid misunderstandings between different stakeholders and to clarify needs based on expected user behavior.
- Domain Driven Design (DDD): A comprehensive approach that considers the entire software production chain, from requirement elaboration to delivery, including software architecture.
Managing Technical Debt Rather Than Ignoring It
Without these methodologies, it’s possible to manage—at least initially. But, as our expert warns, “After 2-3 years, a development team that doesn’t apply Clean Code principles will start to feel the strain.” The absence of Clean Code introduces difficulties into the daily work of teams. That’s why it’s so important to “make the sponsor understand that their real concern is not an extra two days for software delivery but technical debt. What they save at the beginning, they will have to spend at the end.”
Clean Code has the advantage of providing consistency in delivery capacity, giving visibility to the sponsor. However, it doesn’t eliminate technical debt entirely—because that’s impossible! “As soon as you write even a single line of code, you add a piece to the ‘technical debt machine’.” The challenge? Learning to manage this debt. This requires “not considering testing, understanding the business by developers, team interaction, or their seniority as optional.”
3. Clean Code: How to Apply It Daily?
Understand What’s Blocking
Youthfulness is often a factor when our experts are called upon by our partners. But the inexperience of teams alone doesn’t explain the absence of Clean Code—it’s more of an “aggravating circumstance.” It can be difficult for a young developer to feel confident enough to demonstrate why their methodology is relevant to a given business need and to resist the pressure to prioritize speed.
Aurélien Castellarnau observes that “developers have a real duty of pedagogy. Today, more than ever, they need to be able to explain what they do and why they do it the way they do.” But to achieve this, the collaboration between sponsors, beneficiaries, and developers must be as close as possible.
Understand the Business and Its Needs
Developers need to take an interest in the business they are asked to automate, understand the professionals’ needs, and consider the potential uses of the emerging software.
“Software craftsmanship provides teams with tools to facilitate interaction between business and developers.” Developers can rely on the work of “functional experts,” whose task is precisely to understand how the business operates. Why not also organize event storming sessions? These workshops can be invaluable “for working on modeling the actions performed daily by various business roles.”
Understand the Tools at Our Disposal
Other tools include pair programming or mob programming, where two or more developers work together on the same task. The former allows multiple perspectives on the code and helps catch bugs as soon as they are introduced; the latter leverages collective intelligence in emergencies and beyond.
Both approaches highlight the importance of the “community of practice” concept in the Software Craftsmanship manifesto. Our expert adds, “I strongly encourage companies to ask themselves if their teams communicate enough with each other or if dedicated spaces for knowledge transfer exist.”
Proof, if more were needed, that clean code is written by many hands, not alone behind a computer screen!
Clean code is simply code that is readable for everyone who may need to look at it at some point.
If your code is difficult to evolve or reuse in a new project, presents numerous dysfunctions, is unnecessarily repetitive or opaque, it’s likely not as clean as it should be.
Originating from software craftsmanship, the Clean Code approach is based on the quality of written code and, more importantly, on the community spirit among developers and continuous interaction between them, teams, business units, and sponsors.