Clean Code: Writing maintainable, readable and testable code
Clean code is a term used to describe software that is easy to read, understand, maintain and test. In this blog I want to summarize some important principles and provide an entry into the topic for beginners. Besides, the blog shall connect to the style guide repository, the books and current initiatives where experts can contribute. If you do not want to miss an update on clean code, test automation, code reviews, unit testing, decision making, testability and other engineering / craftsmanship / architecture topics, subscribe to the brand new newsletter.
What makes code clean?
Achieving clean code involves following a set of best practices and standards, such as using meaningful names, keeping functions small and focused, and using comments sparingly. Having a code base, which is readable and maintainable is essential for sustainable development. The books Clean Code from Robert C. Martin, Code Complete from Steve McConnell, The Pragmatic Programmer from David Thomas/Andy Hunt, and some other books contain many best practices and examples for clean code.
What is code that’s not clean?
Code that is not clean is code that is difficult to read, understand, and maintain. It may have poor organization, confusing or misleading names, inconsistent styling, and other issues that make it harder to work with.
Some examples of code that is not clean might include:
- Code with long, complex functions that are difficult to understand, test and maintain.
- Code with poor naming conventions, such as variables with short, non-descriptive names, or functions with names that do not accurately reflect their purpose.
- Code with inconsistent styling, such as inconsistent indentation or spacing, which can make it harder to read and understand.
- Code with unnecessary or redundant code, which can make it harder to maintain and understand.
- Code which making test automation hard, e.g. static coupling between classes.
Overall, code that is not clean is often more prone to errors and bugs, and can be more time-consuming to work with, as it requires more effort to understand, test and maintain.
Benefits of Clean Code
There are many benefits to writing clean code, including:
- Improved readability and understandability: Clean code is easier to read and understand, which can make it easier for developers to adapt, debug, and maintain.
- Reduced risk of errors and bugs: Clean code is generally more reliable and less prone to errors and bugs, as it is easier to understand, test and maintain.
- Increased productivity: Clean code is easier and faster to work with, which can increase developer productivity and efficiency. According to a meta study unhealthy code can contain more than 15 times more defects and reduce productivity by a factor of 9.
- Increased ability to adapt and evolve: Clean, modular code is easier to modify and update, which can help the software evolve and adapt to changing requirements over time.
- Improved team collaboration: Clean code is easier for team members to understand and work with, which can improve collaboration and communication within the team.
- Better long-term maintainability: Clean code is easier to maintain and update over time, which can save time and resources. And reduce risk if engineers move to other projects or leave the company.
- Increased code reuse: Clean, modular code is easier to reuse and repurpose in different contexts, which can save time and resources.
- Better performance: Clean code is generally more efficient and can run faster, as it is less complex and easier to optimize when needed.
- Improved code review process: Clean code is easier to review, as it is more organized and easier to understand. This can lead to more efficient and effective code reviews.
- Enhanced reputation: Writing clean code can help enhance the reputation of the developer or development team, as it demonstrates a commitment to quality and professionalism.
Overall, clean code can help ensure that your software is reliable, maintainable, and easy to work with, which can lead to increased efficiency, productivity, higher quality, and higher satisfaction of developers and users alike. The benefits of clean code extend beyond just the development process and can have a positive impact on the long-term success of the software and the team working on it.
Important Clean Code Principles and Examples
First lets summarize some important principles for clean code and provide some simple examples. For every principle there is a lot more to learn in the style guide and the books.
- Clean code makes it easier for developers to understand, modify, and maintain a software system. When code is clean, it is easier to find and fix bugs, and it is less likely to break when changes are made.
- One of the key principles of clean code is readability, which means that code should be easy to understand, even for someone who is not familiar with the system. To achieve this, developers should e.g. use meaningful names for variables, functions, and classes.
- Another important principle of clean code is simplicity, which means that code should be as simple as possible, without unnecessary complexity. To achieve this, developers should avoid using complex data structures or algorithms unless they are necessary, and should avoid adding unnecessary features or functionality.
- In addition to readability and simplicity, clean code should also be maintainable, which means that it should be easy to modify and update the code without breaking it. To achieve this, developers should write modular code that is organized into small, focused functions, and should avoid duplication of code.
- Finally, clean code should be well-documented. This means that it should include clear and concise comments that explain the purpose and functionality of the code. However, comments should not be used to explain the code itself; the code should be written in a way that is self-explanatory.
Overall, clean code is an essential part of software development. It makes it easier to understand and maintain a system, and can help to prevent bugs and other issues.
The Clean Code Style Guide Repository
Under the CC BY 3.0 license and open to contributions from inside and outside of SAP, we hope that this repository will help developers worldwide to make their code a little cleaner, day by day.
The long term goal of the style guide repository is to cover the most important programming languages in the SAP world. So far only ABAP is covered, but I am convinced that more is to come. Maybe we will also be able to cover Java, TypeScript, Kotlin, Go and more – rather a wish than close to reality.
The Clean Code Book
There are several books, which cover the topic in detail, explain the reasoning and apply it to specific programming languages.
The books are also very well suited for beginners or starters to learn the programming languages. Or colleagues who already mastered Clean ABAP and want to learn Clean SAPUI5. And even experts in the programming language mentioned that they learned a lot and it was a source of inspiration.
A Foundation for Improvement
The main benefits of having a common understanding of a code style in a given programming language are improved maintainability, readability and testability. But there are also many other benefits and new possibilities, which this blog explores in more detail:
- Why have a common set of rules? As an organization grows it helps to keep the code base consistent and allows to let the developers focus on the important aspects. There will be less conflicts about basics (e.g. formatting) due to a standard code style.
- Fostering the principle of optimizing code for the reader: Given that code will be read far more often than it is written, an important principle for all rules is to optimize for the reader not the writer. Therefore the style guide weighs readability higher than using powerful expressions, which let the writer express something concisely, but are later hard to read.
- Consistency of the code base: If the code base is built with the same principles and style guide in mind, it allows engineers to jump into an unfamiliar part of the code and make improvements quickly.
- Improve Developer Experience: Having a consistent style guide creates an ecosystem on its own and allows to improve the developer experience. After the style guide was published in 2019, the community started to create tooling for improving code reviews, documented code review practices, extended static code checks, developed training formats and made some tooling to automatically correct code. This consistency created the foundation for several InnerSource / open source projects, platform improvements and triggered the exploration of further ideas.
- Scaling an organization: As an organization grows it is important to have a common understanding of the code style. It helps to ramp up new developers more quickly and focus the time on pair programming or code reviews on other aspects.
- Also other roles — not only developers — benefit, e.g. consultants who need to make extensions or SRE (Site Reliability Engineering) teams who need to improve operations.
- The consistency also improves the long-term maintenance since new engineers taking the ownership can understand more quickly and maintain the code.
- The style guide allows to enforce rules with static code checks or even develop automatic corrections. So some discussions do not take place anymore, which allows to focus the developers time on more important aspects..
With the success of the style guide and number of improvement proposals there comes the need for a more formal process when it comes to reviewing improvement proposals. To make the whole process transparent and have clarity for making decisions.
This includes clarity on how those should be opened, are processed and the typical timeframe in which somehow can expect a decision. Besides, especially for changes with a larger impact (e.g. incompatible changes) we need a formal process for decision making, since those changes will also be reflected in static code checks and by that affect a large number of developers.
In the last months we have worked on documenting the whole process and written down our guiding principles for involving the community and making decisions. The process will soon be published.
Subscribe to Newsletter to stay informed
If you do not want to miss an update on clean code, test automation, code reviews, unit testing, decision making, testability and other engineering / craftsmanship / architecture topics, subscribe to the brand new newsletter. The newsletter will not only be used for sharing knowledge, but also offer opportunities for collaboration, building communities and co-creation.
No one feels the value of clean code than some one like me in SAP operations especially at the hour of need. Not to forget the benefit in terms of reduced business impact and MTTR! Overall great blog and must be made mandatory for all coders ! Thanks for sharing your thought!
Coding is fun, but as enterprise business software developers we need to think in terms of configurable software systems. Coding will create software that require long run maintenance, whereas configurable systems are robust.
The guide respects also ABAP Programming Guidelines and DSAG's Recommendations for ABAP Development , right?
Definitely some conflicts there, e.g. with regard to variable naming, especially with regards to prefixing variables with type/scope information, where clean ABAP recommends leaving those out.
But the Clean Code/ABAP approach definitely has merit and good reasoning behind it.
Thanks for sharing
I am a big advocate for these clean code concepts and practices, and we're working to implement them on our projects. However, it seems like the biggest missing piece in this journey is something you mentioned: tooling to automatically correct code, and ensure compliance. This is commonplace and typically simple to implement in other technical stacks, but is severely lacking for ABAP.
Teaching these concepts to our engineers is great, but in my opinion that only will go so far without the automation in place to automatically make fixes, and then enforce the styles and guidelines.
We are using codePal for ABAP for validating clean code. This works well, but it is a static check and doesn't include automatically correcting/formatting code. Are there other tools that exist today for this?
Hi Josh, maybe there will be soon a OpenSource tool available, which can act as a great first step towards more automation.
To clarify expectations for the OpenSource Style Guide. Everyone in the maintainer team does the style guide as side activity and is involved deeply in product development, so only can spend a small amount of time each week.
We have just built the team for making decisions and got started with the process, so far we focused on open pull requests (now only 5 are left). We will need some time to handle the open issues and coming up with a adjusted system. If you have ideas how we can tackle that as a community. Let me know.
For prioritizing issues and decide which issue to address first, you can vote for the issues and leave a comment. We will then be able to see the priority in a list. You can vote by using thumbs-up in the GitHub issue. https://github.com/SAP/styleguides/issues?q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc
Please leave a thumbs-down when you think the change is not valuable or should not be part of the guide due to other reasons.
I all cases leaving comments is valuable (e.g. why something is relevant or also when something should not be included).
If there seems to be agreement, it also helps us if you create a pull request for the issue.
Pull Requests have higher priority for the maintainer team.
Great initiative, thank's for that.
If you want to participate in shaping the future of the Clean Code guide for ABAP. There are 5 Changes (Pull Requests) ready for decision.
If there are no valid reasons against the changes, those will be merged in two weeks.