Glossary
By the Glue Team
Code health is a measure of the overall quality, maintainability, and sustainability of a codebase. A healthy codebase is clean, well-tested, well-documented, and easy to modify without introducing bugs. Unhealthy code is tangled, poorly tested, creates constant production incidents, and gets slower to change over time.
Code health encompasses multiple dimensions: code quality (structure, clarity, adherence to standards), test coverage and test quality, documentation comprehensiveness, technical debt levels, and the velocity at which developers can safely add features.
A healthy codebase exhibits:
An unhealthy codebase shows:
Code health directly impacts business outcomes:
Velocity: Healthy codebases are fast to modify. Unhealthy codebases slow down over time as developers spend more effort on defensive coding, testing, and debugging. A team with healthy code ships twice as fast as a team dealing with code health issues.
Reliability: Well-tested, well-documented code breaks less often. Unhealthy code generates constant production incidents. That's not just customer frustration—it's team time consumed by firefighting instead of building.
Cost of Change: Adding features to healthy code is straightforward. Adding features to unhealthy code requires understanding complex interactions, risky refactoring, and extensive testing. Estimates become unreliable.
Hiring and Retention: Developers prefer working with healthy code. Working in a codebase where every change is risky and every deployment is scary causes burnout. Healthy code improves retention.
Technical Debt Accumulation: Unhealthy code accumulates technical debt rapidly. Each workaround creates another special case. Each undocumented decision creates tribal knowledge. Debt compounds.
Risk Management: Unhealthy code is risky. You can't refactor confidently. You can't optimize. You can't migrate to new technologies. You're locked into the current design even if it's wrong.
Code health is multifaceted:
Code Structure: Is the code organized logically? Are responsibilities clear? Can you find what you're looking for? Poor structure means related logic is scattered across the codebase. Good structure groups related logic together.
Test Coverage: What percentage of code is covered by tests? But more importantly: are the tests good? A codebase with 100% test coverage but useless tests is unhealthy. Good test coverage means the important paths are covered with meaningful tests.
Documentation: Is critical logic explained? Are decisions documented? Do README files help new people onboard? Good documentation enables independence. Poor documentation creates dependency on experts.
Complexity: Are functions simple and focused? Or are they 500-line monsters doing ten things? Simpler code is healthier. Complexity is measured in cyclomatic complexity, but also in how hard it is to understand something.
Dependencies: Do modules have clear boundaries? Or is everything tightly coupled? Loose coupling means you can change one thing without breaking everything.
Technical Debt: How much of the codebase are workarounds? How many special cases exist? Technical debt is incurred debt—things you built fast instead of right. It accumulates and slows future work.
Code Standards: Are style and patterns consistent? Do code reviews enforce standards? Consistency makes code easier to understand. Inconsistency means each file has different patterns.
Code health improves through sustained practices:
Testing: Write tests as you code. Aim for high coverage on important logic. Make tests part of your definition of done.
Code Reviews: Reviews catch issues early. More importantly, they're a learning opportunity. Consistent standards emerge through review discussions.
Refactoring: Regularly improve code structure without changing behavior. Reduce complexity. Break up large functions. Extract common patterns. This is ongoing, not a one-time project.
Documentation: Document why decisions were made, not what the code does (code shows what). Explain complex algorithms. Keep README files current.
Technical Debt Management: Track technical debt. Prioritize paying down the debt that slows your team most. Don't let debt accumulate infinitely.
Standards and Linting: Enforce consistent style through automated tools. This prevents style debates and catches common mistakes.
Continuous Integration: Automated tests on every commit catch issues early. This gives confidence that code works.
Glue helps improve code health by visualizing technical debt, identifying complexity hotspots, and surfacing features that might have duplicate implementations. When your team understands the codebase deeply, you can make informed decisions about what to refactor and where to invest in paying down debt.
"Code health is just about following style guides." False. Style is one dimension. Code health includes structure, testing, documentation, and complexity. Well-formatted bad code is still bad code.
"100% test coverage means code is healthy." False. Bad tests don't help. You need meaningful tests that verify important behavior. 70% coverage with good tests is healthier than 100% coverage with pointless tests.
"Code health is optional; we can refactor later." False. Later never comes. Technical debt compounds. Code that's slow to change now will be impossible to change in a year. Invest in health continuously.
"We can't improve code health while shipping features." Partly false. Yes, you need to balance new features with health. But good practices (testing, code review, small changes) actually speed up feature shipping by reducing bugs and rework.
Technical Debt: The accumulated cost of shortcuts and poor decisions that slow down future development.
Code Complexity: The difficulty of understanding code, measured through metrics like cyclomatic complexity.
Test Coverage: The percentage of code exercised by automated tests.
Developer Onboarding: Healthy code enables faster onboarding because it's clearer and better documented.
Q: How do you measure code health? A: Multiple metrics: test coverage percentage, defect rate per deployment, mean time to recovery from incidents, deployment frequency, code review turn-around time, new developer time to first meaningful contribution. No single metric captures it—look at trends across multiple dimensions.
Q: Can you have high code health in a legacy system? A: Yes, but it requires sustained effort. Legacy systems often start with low health due to accumulated technical debt. Improving requires steadily refactoring, adding tests, documenting decisions, and paying down debt. It's possible but slower than building health from the start.
Q: What's a realistic test coverage target? A: For critical business logic, aim for 80%+ coverage. For less critical code, 50-70% is reasonable. The key is covering important paths and edge cases, not chasing percentage for its own sake.
Keep reading
