How to Write Clean Code

What Is Clean Code?

Clean code is simple and understandable. It allows the finished product to be easily enhanced and maintained. 

Clean code was a term coined by Robert C. Martin. It's the subject of his book, “Clean Code: A Handbook of Agile Craftsmanship”. This book is the definitive work on the topic. I highly recommend it.

How to Write Clean Code

Here are the basics you'll need to know to write clean code. 

1. 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.

You should 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 (e.g., performing actions) and those that are queries (e.g., 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. But 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.

[Related Blog: What Is Version Control?]

2. Use Comments

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

Even if you’re a startup building a demo, you might as well start the processing of documenting what you're 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.

3. Respect Your Team

When you do check something in, you should be confident that the work you have completed is 100% defect-free. If you are in a Continuous Integration (CI) workflow, and your code breaks the build, it’s annoying and embarrassing. Especially 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. 

4. Test Code

The simpler the code is, the fewer defects. The fewer the defects, the less expensive it will be 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.

5. 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.

[Related Blog: Using Open Source Code in Proprietary Software]

How Do You Write Clean Code? With Helix Core

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.

Another good step is using Helix Core to write clean code. 

Helix Core is version control software. It keeps everyone on your team on the same page, using the latest version of the code. This helps you ensure that the clean code is used. And if there's a bug, Helix Core makes it easy to trace it back the version it was introduce in.

Learn more about how Helix Core can help you implement clean code. You can get started for free for up to 5 users.

Try Helix Core