Ask any coder what the bane of their existence is, and the answer will likely be the same. There are few sins as egregious as unclean code. While we may be quick to attribute this habit to others only, we’ve no doubt all been in the situation where we’ve revisited code months after its creation only to scratch our heads in confusion and think, “Just what was I thinking here…?”
What is Unclean Code?
Unclean code is code which is messy and difficult to decipher. Just because a computer is able to read and understand a piece of code, that doesn’t mean that it is being written properly. Functional code is not the same as clean code. A piece of code might work very well when it’s executed, but if the author of that code departs a business, and subsequent bug fixes or updates need to be applied, it will cause problems down the road.
Code that is difficult for other coders to read and understand can create very serious problems for any development team. It is quite normal to have different coders working on different tasks for the same application, but it’s vital to be able to show code written by one coder to another coder, and have them decipher exactly what is going on straight away. Complexity and incomprehensibility are only going to extend the lead times within your technology value stream. This is especially true if you’re working in isolation. It can be months or even years before you may revisit certain lines of code, and even if it’s clean, it can take time to relearn what you were doing to write it in such a manner. Unclean code makes that process exponentially longer.
Unclean code can cause no end of untold problems for a development team. In fact, it is no exaggeration to say that unclean code has the potential to completely sink a business because of the technical debt incurred by poor coding practices.
Thankfully, there are a number of best practices and other conventions that coders would do well to follow in order to make their code easily readable by others.
A Cohesive Team
In situations where one person is writing code purely for their own benefit, unclean code is not an issue (although it does imply that the coder is picking up some bad habits). However, the vast majority of code is either written as part of a team, or it is written with the intention of making later adjustments or improvements. Whatever the circumstances, if code is unclean it will be difficult for other coders to make sense of or work out where issues lie. This is not at all conducive to collaborative work or teamwork within a business, or even within a single department.
Developing a series of best practices in-house and ensuring that all your coders are observing them will ensure that all your coders are producing clean code. This methodology means that you can easily pass code between your coders so that other people can contribute to it, and you will be able to solicit a wider range of opinions. Encouraging clean code practices will also ensure a higher sustained level of code quality.
There is something meditative about coding. Anyone with a reasonable amount of coding experience will be able to attest to this fact. Composing lines of code requires careful thought and consideration. For any given problem, there are a multitude of potential coding solutions, some simple, some complex. Individual coders will have their own approaches to different problems and will also find their own individual solutions.
With so much space for individual thinking, reasoning, stylistic, and syntactic choices, your coders will naturally tend to produce wildly different solutions to the same or similar problems. Ensuring that your coders are always producing clean code will guarantee that, even if they each take slightly different paths in order to solve any problems that they have, they will always be outlining those steps in a way that their fellow coders can understand. It is hard to overstate just how much this can improve the efficiency of your own and your team’s workflow.
Show Your Workings
When coders are faced with one another’s work, either for the purposes of evaluating it, or in order to help bug fix or improve upon it, it can often be difficult to work out what’s going on. Even with properly formatted code, one coder might look at the solution of another coder to a particular problem and become too hung up on why they have taken the approach that they have to even consider the validity of the solution.
Encouraging your team members to write clean code will also encourage them to make it clear why they are taking the route that they are. If you are coding as part of a team, one of the worst sins you can commit is to not create your code for the benefit of those who have to read it later. Hopefully, the original coder will be available to talk their co-worker through the code they have written, and why they have written it the way they have. With clean code to refer to, it is much easier for coders to discuss their code with one another.
Code Style Guides
At Caylent we recommend using a code style guide, such as the ones outlined here by Google on Github to help you and your team write cleaner code. To achieve this, adopt the following strategy:
- Set up the first unit test to lint check. For example, shellcheck for Bash, flake_8 for Python, etc.
- Agree with the team to adopt a pre-written code style (see here for your relevant code language).
- Ensure code reviewers are checking that everything is well commented and has README.md.
- Ensure peer and code reviews happen (preferably within minutes, not hours, and certainly not within days).
Remember, a code review that checks it’s written to the adopted code style, in general, could be done by someone that doesn’t necessarily understand the system you are working on. That help alone can improve your entire system no end.
Coding is an art form quite unlike any other. The cold, logical, and rigid manner in which most people think of computer code does a disservice to the level of creativity that coders must be able to display to one another. By encouraging your coders to write clean code, you will give them the freedom to be creative, without having to worry about future readability.
For more on code best practices, read our post on DevOps and DRY.
Caylent offers DevOps-as-a-Service to high growth companies looking for help with microservices, containers, cloud infrastructure, and CI/CD deployments. Our managed and consulting services are a more cost-effective option than hiring in-house, and we scale as your team and company grow. Check out some of the use cases and learn how we work with clients by visiting our DevOps-as-a-Service offering.