What is code quality? #
Definitions of code quality is pretty subjective and different from company to company. Developers also have different opinions on what is good code.
In general, code quality is a way to talk about how correct, readable, reusable, maintainable and efficient code is.
- correct: free of bugs and errors
- readable: clean and understandable
- reusable: modular and adaptable
- maintainable: easy to refactor and extend
- efficient: optimal performance
Why is code quality important ? #
- Reduces bugs and errors → faster, more stable releases
- Efficient code scales better → improved UX, reduce compute costs
- Helps developers understand, review, collaborate and build upon their own code → faster iterations
How to measure code quality? #
Quantifying code quality is challenging, but these metrics provide useful signals:
- Test coverage
- Also integrate coverage reports with your platform, e.g. GitLab Code Coverage
- Production bug count
- E.g. Sentry (Error monitoring tool)
- Code churn: frequency of edits to the same code—high churn often indicates implementation struggles
- Cyclomatic complexity: measures code path complexity
- Confidence in refactoring: how comfortable the team feels changing code or upgrading dependencies
How to maintain code quality? #
Correctness #
- first and important step, engineers need to ensure the code follows the requirements and specifications.
- It also means the code is free of bugs and errors.
In practice #
- Enforce type checking for dynamically-typed languages to catch type errors at compile time.
- Setup unit tests and integration tests in CI to catch bugs and errors early.
- Take Test-driven development (TDD) as a guide.
- Write unit tests covering edge cases and common scenarios.
- Test integration happy paths at minimum (adjust based on team needs) since it takes more time to write and maintain.
- Still, race condition remain challenging to test: Go has a Race Detector but for Node.js.
- Run linter checks in CI to catch code smells
- e.g. eslint, golangci-lint
- Consider configs from big tech: e.g. eslint-config-airbnb
- Fix flaky integration tests ASAP.
- "Don’t live with broken windows." - The Pragmatic Programmer
Readability #
Code should be easy to understand, review, and maintain.
Complexity #
Complexity directly impacts readability.
A Philosophy of Software Design by John Ousterhout explores software complexity (e.g. cognitive load) and strategies to reduce it.
In practice #
- When writing code, follow Clean Code principles:
- meaningful naming
- function should do one thing only
- comments should explain why not what.
- Strategic Programming over Tactical Programming
- Use code formatter: e.g. prettier
- Follow language-specific guides: e.g. Effective Typescript, Effective Go
Reusability #
- When implementing similar logic across entities or services, reusable code becomes valuable.
- However, abstraction should be done with care, premature generalization actually creates complexity. see Rule of three
In practice #
- Follow the DRY principle thoughtfully.
Maintainability #
Maintainability is about how easy it is to refactor and extend the code.
In practice #
- SOLID principles
- The software is divided into discrete, independent modules or components, each with a clear and specific functionality.
- "Module should be deep." - A Philosophy of Software Design
- Proper management of dependencies ensures that external libraries or components can be updated or replaced without major disruptions. E.g. dependency injection, version control, and modular design.
Efficiency #
Efficiency can be defined as, using the resources optimally where resources could be memory, CPU, time, files, connections, databases etc.
In practice #
- write efficient code, understand and minimize time and space complexity of the code.
- Measure before optimizing: Don't optimize performance before you measure it. E.g.
- End-to-end: Sentry - Performance Monitoring
- Database: Mongo Atlas Monitoring
- Frontend: Lighthouse
Further Reading #
- How to create software quality. by Will Larson discusses software quality in a broader sense.