How to build a culture of code quality
A code quality culture is essential to stay ahead of your competition. High code quality ensures your codebase is maintainable, scalable, and efficient. While a culture of code quality is an internal aspect of your engineering team, it directly affects your end users. High-quality code allows you to ship new features faster, improving the user experience.
CTOs and engineering managers need to establish agreed styles and standards to build a culture of code quality. They should also track high-quality issues, be awesome at code reviews, track code quality metrics, and engage in peer mentoring.
This blog post will discuss each of these core areas in detail.
1. Establish agreed styles and standards
Your team needs agreed styles and standards for documentation, code, and code comments. These standards will span simple formatting rules to the way you structure larger chunks of code.
These styles and standards will ensure that the code is consistent and readable, which minimises the risk of accidentally accumulating tech debt.
- Code Style Guides – Keep consistent by establishing conventions for things like naming, spacing and indentation. Try the Airbnb, Idiomatic, or Google style guides.
- Code Comments – Establish conventions to ensure comments are useful. Here’s a great guide. Never allow your team to push TODOs – they’re neither visible nor actionable. Use a tool to track issues linked to code from your IDE.
Having a set of agreed standards makes it easier to identify code quality issues and provide feedback during code reviews.
Tip: Don’t overdo your style guides. A style guide should set strict naming, spacing, and indentation rules to improve readability. Further, it should set rules on how to capture business context. There’s no need to regulate each line of code. Setting too strict guidelines can adversely affect your engineering team’s productivity.
2. Track high-quality issues
Tracking high-quality issues to manage tech debt properly and prioritise quality-related issues is crucial.
One of the main barriers to this is that issue trackers like Jira are not user-friendly and don’t link issues directly to code. That means issues aren’t visible or actionable. When working in your editor, you don’t see these issues that can be instrumental in improving code quality.
Use the right tool to bring issue tracking into the code editor. I use Stepsize, which lets you create and manage issues linked to code directly from the IDE. Tracking high-quality issues makes it possible to prioritise and fix the most critical issues first and manage tech debt more effectively.
3. Prioritise and fix quality issues
Quality issues fester and have huge costs of all kinds. We need to prioritise and fix code quality issues to ensure they get resolved before the impact spreads.
Here are a couple of approaches you can take:
- Allocate 15-20% of your engineering resources each sprint to fixing tech debt
- Regularly run a sprint dedicated to tech debt.
The best strategy is to continuously address tech debt by allocating resources weekly to solve quality issues.
In the end, both approaches resolve tech debt, improve the maintainability of the code, and ensure that the code is scalable and efficient. It depends on the size and complexity of your project and team to determine the best strategy.
4. Be awesome at code reviews
It’s all too easy for code reviews to more of a hindrance than a help. But code reviews are an essential part of building a culture of code quality.
Reviewing code makes it possible to catch quality issues early and provide feedback to the engineer who wrote the code. Besides that, code reviews are a clever mechanism to passively gain knowledge about different or new areas of your codebase.
To be awesome at code reviews, you need to have a clear process to provide consistent feedback.
Most engineering teams create a “Definition of Done” (DoD), which acts as a checklist for code reviewers to verify if all quality requirements are met.
Here’s a simple example of a Definition of Done:
- Unit tests should pass
- Integration tests should pass
- Technical debt issues are logged
- The codebase is clean of TODOs
- Critical business logic should be documented with code comments
- All code commits should follow the commit guidelines
- All code should follow the code style guide
- Product Owner accepts the User Story
Tip: Use tools to automate these processes or surface issues that might arise during code reviews.
- Husky leverages git hooks. It can be used to lint commit messages and code, run tests and more. ESLint and Prettier are great tools to use in combination with Husky to format code according to your code style guide.
- Stepsize helps enforce technical debt best practices throughout the software development lifecycle, including in pull requests. During PRs, it surfaces existing technical debt issues and surfaces TODOs.
- Snyk Code helps you to perform static analysis for your code to help you find different types of errors, like security or performance errors.
Having a clear code review process and consistent feedback can improve the code quality over time. Doing this ensures that the code is scalable, maintainable, and efficient.
5. Track code quality metrics
To measure the success of the efforts to build a culture of quality, it is vital to track code quality metrics. Read more about metrics here.
- Code Complexity – One of the most common metrics to track is code complexity. Code complexity tells you how complicated a piece of code is for a developer to understand.
- Number of comments per 1000 lines of code – The number of comments in your code helps you understand its complexity. If you consistently track this metric, you can see how the complexity of your code changes over time. An increase in the number of comments per 1000 lines of code means that your code needs more context to be understood by developers.
- Code Cohesion – Code cohesion measures how well-structured and organised your codebase is. A highly-organized codebase is easier to understand, maintain, and modify, which improves code quality. Moreover, a highly-organized codebase allows developers to work more efficiently.
By implementing code quality metrics, you can keep an eye on the health and quality of your codebase.
6. Peer mentoring
Senior engineers play an essential role in creating a positive culture and supporting junior engineers in writing higher-quality code.
Here are some examples of peer mentoring techniques:
- Knowledge sharing: Senior engineers can share knowledge via informal conversations, workshops, or all-hands meetings. These meetings help junior engineers understand the business context and associated technical decisions better.
- Code reviews: As mentioned earlier, code reviews are a great tool to share knowledge and provide feedback. Try to sit with a junior engineer when doing a code review to make the review more actionable and offer a hands-on learning experience.
- Code pairing: Pair programming is a proven method to create a shared, hands-on learning experience. This technique involves working with a junior engineer to write code and solve problems. It also allows for real-time feedback.
By actively implementing these peer mentoring techniques, you create a positive learning experience for junior engineers, contributing to the overall code quality.
I have seen time and time again that the most successful engineering teams have code quality engrained in their behaviour. They…
- Track high-quality issues, prioritise and fix them, and use the right tools for the job. Stepsize is built for this.
- Are efficient at code reviews. Try Husky, Stepsize and Snyk.
- Support individual engineers’ progress.
You can drive higher performance in your engineering team by promoting a culture of code quality. These behaviours protect the codebase and product over the long-term.