If you are working on a development team and in charge of managing multiple source codes, it’s crucial that you treat the code with the utmost care to keep everything going because, over time, the project and your number of teammates will get larger and larger. Now, maintaining the cleanness of the codebase can be a challenging and time-consuming task since new joiners with different skills and mindsets can bring difficulty to the onboarding of delivering code.
Because of that, building a culture that emphasizes the importance of clean code at the beginning is crucial to ensure your team’s long-term success.
The idea of this article is to list out best practices to follow so that every development team member can count on building a culture of keeping the code clean.
Why Should You Keep the Code Clean
Imagine you are a junior developer who doesn’t know about clean code, and you’re working on a functioning system that is being maintained clearly by dedicated developers from your team. Your manager demands you implement a new feature. With your skills, you can then easily implement it and deliver the code on time, but because you lack knowledge about clean code, you unintentionally deliver unstructured code — which creates technical debt.
As time passes, the code you delivered propagates and adds chaos to the system because other newcomers are imitating your code. Consequently, each subsequent change brings more costs and risks to the project, leading to rigidity, fragility, immobility, and lower resilience.
This is similar to the “Broken Window” Theory, which states:
“Consider a building with a few broken windows. If the windows are not repaired, the tendency is for vandals to break a few more windows. Eventually, they may even break into the building, and if it’s unoccupied, perhaps become squatters or light fires inside.”
So what do we learn from the “Broken Windows” Theory?
The theory suggests that things can turn bad quickly when one bad behavior happens in a clean place without immediate corrective action. This leads to the same results as the broken window — not fixing it will lead to breaking the rules without consequence. When applied to software development, the story is more straightforward. If someone leaves the code unstructured, this can cause roots of entropy within the system, and the final result can be the collapse and loss of control of the project, which can cost billions every year.
Detect Red Flags in Your Codebase
Since software development is very complex and requires insane detail in craftsmanship, the border between clean and functioning features and rotted ones hangs on the behavior of developers who maintain those features. For a feature to get out of control, there are multiple factors involved:
1. Neglecting from developers
I should mention that every failed system is not backed by technical aspects but mainly because of human decisions. Perhaps, this is the most common and, sadly, the fastest way to destroy the project. No one likes someone who does not want to be responsible for their actions.
In software development, if it is not a personal project, you will likely work with many people. Cooperation and communication are key factors, but some people think their time is so precious that they can skip reviewing their work, and this mindset leads to tons of entropy. Avoid this and accept it. No one can write perfect code in a single try.
2. Over complexity
Sometimes, developers want to prove they are Tony Stark in software development.
I am a 10x developer, baby!
So, what do they do? Replace three lines of code with a single nested line with the weird-looking niche syntax of your language. Of course, this approach will confuse readers and leave them with more questions than answers. But who cares — The important thing is that you feel like a genius, right? (Nope)
Overengineering a simple solution will not prove you are a genius. It verifies you do not understand the human factor in software development and undermines code quality and maintainability.
3. “Let’s guess what this variable means”
One of the most difficult parts of being a programmer is naming variables. Well-named variables or functions can easily tell readers what they do. In contrast, bad naming makes it harder to read and takes longer to understand.
Reading code with poorly named variables is like playing a guessing game. Readers must take all the clues you scattered over the source code and piece them together to understand what you want to do in the feature.
Usually, your bad naming behavior will be caught during the coding review, but let’s be honest: why start a time-consuming argument when you can just follow the naming conventions?
4. Duplication, duplication, and duplication
What is important should be shouted three times. Repeated code can be tempting, and you may think your code is so supreme that it should exist in multiple places in the project. However, think of the consequences when the feature’s requirements change, and you are in charge of updating those “supreme” codebases.
Here’s what will happen: you’re likely to miss one or two instances of the copied code, then have to scan the project again multiple times. I won’t even go into the headache of multiple people joining the task to scan and fix the problem. It takes a lot of time and effort and should not be underestimated.
Abstractions are challenging and time-consuming, but focusing on future maintenance is worth your time.
Best Practices To Build the Clean Code Culture
1. Clear definition of clean code
The first and foremost step when you want to create something is to have a clear definition of it. Structuring in source code is a wide area, so it is important to list how clean the code should be taken care of among members of the development team; this will help you agree on the same understanding of what constitutes clean code and what goal you want to achieve.
Popular coding best practice patterns can be good resources for you to define your version of clean code; some are SOLID, DRY (Don’t Repeat Yourself), KISS (Keep It Simple, Stupid), etc.
2. Code reviews
What is the intent of your code? Show me!
Developing a culture needs community interaction, and a code review session is one of those. Usually, a code review should involve two development team members, one not being the code author. Managers of development teams should encourage their developers to code review and send feedback before any changes are delivered to production. Through those activities, a combination of these goals can be achieved:
- Code quality: People are more careful when sending code to review because they know someone will watch, and if the quality is not good, they can be humiliated.
- Detect defect: A study of the Cisco Systems Programming team has revealed that a review of 200–400 LOC over 60 to 90 minutes should yield 70–90% defect discovery.
- Learning opportunity: When joining review sessions, reviewers and the author can learn from each other. They can learn better ways to adhere to coding standards.
3. Continually improve codebases through refactoring
It is a lie to say that the code we deliver will always be perfect. Sometimes, there are moments when the deadline forces us to rush to release a final feature before the scheduled date comes. And this is when our code will not be in the best shape. Sometimes, sloppy code is inevitable. But this does not mean you should ignore or tolerate it.
If you find yourself in a situation where clean code is challenging, and you cannot dedicate enough resources, prioritize the demanding feature but keep notes or comments where you leave unstructured code for future refactoring.
Additionally, a regular checkup can keep the code clean and reduce the impact of possibly rotten code. Remember, even when you do not always achieve perfection in delivering code, a mindset of striving for a cleaner codebase can be helpful for your team’s productivity in the long run.
Every time, you are doing work in an area of the code, always leave the code a little cleaner, not a little messier, than you found it. — Uncle Bob
4. Enforcing coding standards
Although a clean code delivery mindset should be continually trained and improved between developers, we humans are born to make mistakes. Because of that, checking if the code generated by humans is perfectly aligned with coding standards or is not challenging. Therefore, to achieve consistency in the coding style, adding more automation tools that will detect common mistakes may be beneficial; they will provide developers with quick feedback as they don’t have to wait for human interaction to detect the problem.
Commonly used automated tools include Pylint for Python, ESLint for JavaScript, etc. If you use CI/CD, consider integrating those tools into your pipeline to check for coding standard violations during development workflow.
5. Reward clean code achievements
There are two ways that motivate a human into action: necessities or rewards. The same behavior can be applied to clean code best practices, which will ensure structured code is delivered and reduce violations of coding standards.
Recognizing and appreciating developers for their effort to keep delivering clean and structured code can help them take pride in their work which improves and propagates a positive culture to the whole organization.
How Much Clean Code Is Enough?
While clean code should be a go-to approach every software developer should follow, it is evident that always keeping the code clean in every line you write can lead to the headache of burnout because of perfectionistic behavior. Nothing is perfect, so something will always be wrong with your project. If you focus too much on fixing the little details that make you unhappy immediately, you will likely miss the deadly ones, which can be traded with monetary compensation.
In reality, how “clean” your code is can vary and depend heavily on your team’s agreement. While keeping the code structured is important, one should consider other factors that can affect the project’s success, such as time constraints, resource availability, specific requirements, and the collective skills of team members.
Try seeking the balance between other factors while keeping the code clean. Avoid focusing too much on perfection. Instead, if you see something that isn’t clean enough but acceptable to deliver, consider leaving comments for future refactoring. Finally, all I want to say is:
“Great software should be adaptable and prepared for future changes in the business and its definition.”
To get the most out of this article, feel free to complete these challenges 👇:
- Does your organization strive to deliver a clean coding culture or not? If yes, what current approach keeps developers on track with clean code practices?
- Do you believe that clean code is solely the responsibility of individual developers, or should it be a collective effort within a team or organization? Why?
Originally published at https://junedang.com on July 1, 2023.
How To Build the Culture of Delivering Clean Code was originally published in Better Programming on Medium, where people are continuing the conversation by highlighting and responding to this story.