Clean code — a term first coined by Robert C. Martin in his book ‘Clean Code: A Handbook of Agile craftmanship’ — is very relevant in today’s fast-paced, highly complex software development and lifecycle management environments. It makes it easier to evolve or maintain a finished product. Compare it, if you will, to the work of an electrician; a cabinet of tidy wires and connectors, all clearly organized and labeled, will make future changes that much easier and faster, with fewer risks of error and maybe even reduced costs over time.
Part of clean code is also being considerate of others. Writing code that everyone understands, that the developer is confident is error-free and supported by clear documentation is being respectful of other team members. ‘Do as you would be done by’ is an applicable motto here; code that breaks once beyond the experimentation stage is likely to annoy colleagues, be embarrassing for the developer and even damage his or her reputation.
The benefits are inarguable — what’s not to love about code that works better and has a lower cost over time? Yet many do not think it is necessary and view writing ‘pretty code’ as something that could slow down getting a product out to market. They are not trying to create a work of art, I’ve heard them say. The reality is that it can and should be an asset, not a hindrance, particularly if certain good practices (such as naming conventions) are applied.
For more detail into best practices for clean coding I recommend purchasing Martin’s book — but this article provides an overview of the main building blocks of clean code. First, let’s look at a few example scenarios of the consequences of not having clean code.
Missing deadlines. Taking shortcuts while coding may feel like a way to speed up productivity, but in a large organization where teams are dependent upon one another, there can be a domino effect of missed deadlines, impacting other team’s productivity too.
Difficulty making enhancements. One of the tenets of clean code, per Martin, is to make it easier to change. In today’s competitive landscape, responding to customer feedback is critical, and can make the difference between the product being a hit or a miss. When a product ships late, the company’s results can be impacted.
Angering customers. It’s an extreme circumstance, but companies have had their share prices falter and even laid off staff because of customer dissatisfaction due to chronically poor-quality code being released to production. The knock-on effect of, for example, electronics products that have to be recalled because of bugs in the embedded software, can be huge.
Losing the best developers. Solving complex problems and the thrill of seeing code become part of a successful product is what drives the most talented software developers. Spending all your time struggling to fix ugly, dirty code created by your colleagues can lead to exits.
Let’s look at the main building blocks required to create clean code. Remember that code is a language, and like any other language, that means it should be easily understandable and its intent clear. So, first on the list is using formatting, naming conventions and segmentation. Martin’s book goes into more detail, but the basic idea is to break up code into small pieces, writing short functions with fewer parameters and separating out those functions into those that are commands and those that are queries.
Some rework is generally an inevitable fact in most projects and often, the need for that rework may not be discovered until after the software has passed production, such as a user finding a defect. The problem can be exacerbated by Agile, which, while it has many benefits, the iterative nature of Agile processes may mean that John Smith has moved on to the next task, but Jane Brown sitting next to him is evolving John’s code for the next release. This is disruptive and can lead to unhappy customers. Making sure that proper ‘labeling’ is in place right from day one — like a very clear set of road signs — will help simplify and speed up rework.
Use comments are something else to keep top of mind, particularly in largerscale projects involving multiple contributors, but even startups benefit from processing the documentation about what is being built at the beginning, not least because many great products have evolved from what started out as great demos. That means the code will be in play for several years. Another reason for use comments might be that code is not allowed to be checked until it has been documented, something that often happens in large companies with lots of contributors involved.
Unit test cases
Many who have studied clean code concepts also follow the tenets of Test Driven Development (TDD), because it is a process that promotes clean code.
The first step is to write a test. Then, write the minimum amount of code necessary to pass the test. Next, enhance and refactor that code. If the code can be enhanced and the tests still pass, the developer has the assurance that the existing code has not been broken.
As discussed, it’s great to be able to look at source code and understand what it does, through good structure and the inclusion of comments. One of the biggest problems with comments and other documentation, though, is that developers all too often change the code without changing the comments.
Tests should be repeatable, fast, consistent and easy to read. As such, they provide almost automatic documentation, because they show how to use the code, from the standpoint of the original authors. By reading the unit tests, anyone who needs to work with the code, whether testers or other developers, can learn how the author of the code being tested would use that code in production.
Many teams find unit tests to be as important as the code being tested, especially in the context of a larger project where code reuse is critical to meeting a demanding schedule. For this reason, it is critical to write the tests with the same standards of quality as the code itself.
Beyond clean code
Most of these basics for clean code are common sense, but for even the most basic software product to succeed in the market over time, more focus and attention to details around documentation, simplified code and testing are required. Increasingly, products have more at stake than money and pride.
In an age where we’re about to have autonomous vehicles on the road, rules for how code is structured and written have gained importance, and even more diligence needs to be applied to safety and security-critical systems. Industries such as aerospace and defense, automotive, medical device manufacture, and banking and finance have compliance standards for coding that are stringent.
Increasingly, code must be proven to meet industry standards. Static code analysis tools, which scan source code, can detect hidden defects and security vulnerabilities, and ensure compliance with best-practice coding standards. This technology helps ensure code is secure, reliable, and reusable.
There is an added benefit in productivity enhancement gained by relieving some of the mentorship responsibilities of senior developers. Static code analysis can help all team members understand problems with their code and improve their skills.
Creating code that is tidy, comprehensible, ‘plays nice’ with other developers’ code, matters. Plus, rather than slowing down project completion, it can proactively contribute to better productivity in the long run.