Clean code benefits the software delivery process and can be achieved by following these basic principles..
April 5, 2018

Why You Should Write Clean Code

Version Control

Clean code is simple and understandable. When this concept is adopted by a software development organization, it allows the finished product to be easily enhanced and maintained. This is an idea that is hard to argue against but, believe it or not, some will.

The term clean code was coined by Robert C. Martin, and is the subject of his book, “Clean Code: A Handbook of Agile Craftsmanship”. This book is the definitive work on the topic, and I highly recommend it. It explains in great detail how to write clean code.

It would not be possible in a blog post to teach you how to write clean code— you’ll need to buy the book for that. Instead, I’ll explain why it’s important to write clean code, some of the important building blocks, and benefits you can achieve.

The prevalent argument I have seen against writing clean code is, “we are trying to ship a product, not create art”. However, the code created by following clean code principals may look pretty, but far more importantly, it works better and will have a lower cost over time.

Use Formatting, Naming Conventions, and Segmentation

Kent Beck, one of the first practitioners of Agile and the inventor of test-driven development, says code should reveal intention. Any developer should be able to read it and easily understand its intent.

Writing such code can be accomplished in several ways, and Martin’s book includes many ideas. In brief, you would start with formatting, naming conventions, and breaking code into small pieces. Writing short functions with fewer parameters is a key element. Getting more specific, the concept that functions should be separated into those that are commands (i.e. performing actions) and those that are queries (i.e. return data).

A common question at this point might be: What is our goal? To ship or to write understandable code?

From an economic standpoint, shipping is the ultimate goal. However, also from an economic standpoint, it is well accepted that rework due to code that was incorrectly implemented in the first place is costly. Having said this, rework is inevitable in every project. Sometimes it’s because of incorrect specs or stories. That’s frustrating, but not as bad as rework generated by the person sitting next to you.

One big problem is, you may not discover that rework is needed until long after the fact. For example, when a user discovers a defect after the release is in production. And, if your team is employing an Agile process, iteration is likely the name of the game — you may have moved to the next task, but your neighbor is working on your code for the next release. This can be very expensive, both in customer dissatisfaction and in disruption to the team because developers have to go back and address the defect.

Use Comments

Short functions, good naming conventions, pretty formatting. Humans can understand the code. But let’s face it, if you work on a project that is of any scale, you will need comments and documentation.

Even if you’re a startup, and are only building a demo, you might as well start the processing of documenting what you are building at the outset. In fact, many startups have evolved from an award-winning demo into a successful company and the demo code continues in production for several years.

There’s another reason to use comments. If you work at a big company with many teams and developers, you may be required to comment and document from the start. It’s even possible that your code is prohibited from being checked in until such a condition is met.

Respect for Your Team

When you do check something in, you should be confident that the work you have completed is 100 percent defect-free. If you are in a continuous integration (CI) workflow, and your code breaks the build, it’s annoying and embarrassing (if you’re past the experimentation phase). 

If a colleague reviews your code and finds it’s hard to understand, then you’re wasting their time. This can negatively affect your reputation and create unneeded inefficiencies. Therefore, it’s crucial to write clean code and provide an appropriate level of documentation. 

Testing

The simpler the code is, the fewer defects. If there are fewer defects, it will be less expensive to debug. And, the likelihood of rework goes down. It’s also easier to write tests. Many also believe that the best documentation is unit test cases, if they are well-written.

Eliminate Duplicate Code

We live in a world where cutting and pasting code has become a common way of doing things. Sometimes it happens when a project has a large team and development is done by many people of varying skill sets.

One of the biggest problems with duplication is that bugs get copied. Kent Beck expressed it very well, saying everything should be said "Once and only Once." In fact, refactoring to remove duplicate code and discouraging “copy and paste” by developing standards for code reuse are great ways to get better designs and improve overall quality.

Conclusion

To many of us, these are common sense ideas.  Making them part of your day-to-day practice is the hard part. You can start on your journey to becoming an “Agile Software Craftsman” (in the words of Robert Martin) by employing these best practices. Learn how Helix Core can help you implement and test these coding best practices when you sign up for the upcoming live demo.