The document discusses the concept of technical debt, emphasizing its understanding, implications, and the importance of maintaining technical health within software development teams. It outlines principles related to technical debt and provides an action plan for addressing it, including defining technical debt, gathering data, and utilizing tooling to improve code quality. The document advocates for a mindset shift among stakeholders to recognize technical debt's impact on software delivery and development efficiency.

1. Mikael Vesavuori — Technical Standards Lead at Polestar
From Technical Debt to Technical Health

2. Key points
- Understand technical debt and its implications
- Why technical health is something teams should work towards
- Relation to other practices
- Examples and demonstrations of practices and tools for different maturity levels

3. Common
th
ings you might
hear about
te
chnical debt

4. 🤔 “Why didn’t you build it right the
fi
rst time?”

5. 🤔 “Why didn’t you build it right the
fi
rst time?”
🎤 “I don’t think you need that.”

6. 🤔 “Why didn’t you build it right the
fi
rst time?”
🎤 “I don’t think you need that.”
☹ “We don’t have time nor money for nice-to-haves right now…”

7. 🤔 “Why didn’t you build it right the
fi
rst time?”
🎤 “I don’t think you need that.”
☹ “We don’t have time nor money for nice-to-haves right now…”
👺 “So now you want more money to do what you failed to do the
fi
rst time around!?”

8. 🤔 “Why didn’t you build it right the
fi
rst time?”
🎤 “I don’t think you need that.”
☹ “We don’t have time nor money for nice-to-haves right now…”
👺 “So now you want more money to do what you failed to do the
fi
rst time around!?”
😰 “Christ almighty, don’t go telling management about this!”

10. Three things are certain in life:
Death ☠ , taxes 💶, technical debt 📉.

11. — Eric Higgins, https://medium.com/s/story/technical-debt-is-like-tetris-168f64d8b700
“You can’t win. You can only control
how quickly you lose.”

12. Amount of time spent on technical debt and non-productive labor

13. Amount of time spent on technical debt and non-productive labor
~20%

14. Amount of time spent on technical debt and non-productive labor
~20% 31.6%

15. Amount of time spent on technical debt and non-productive labor
~20% 31.6% 23-42%
Sources: Raygun, Stripe, Codescene

16. -€13 867 per month
8 developers á €50K annual salary
31.6% technical debt + 10% unplanned work

17. You are already
paying for that debt.
Unless you
fi
x it, you’ll just continue wasting money.

18. How to go from “debt” 😭 to “health”? 🏃

19. First, we de
fi
ne it.

20. — Philippe Kruchten, Robert Nord & Ipek Ozkaya: Managing Technical Debt: Reducing Friction in So
ft
ware Development (2019), p. 5.
“In so
ft
ware-intensive systems, technical debt consists
of design or implementation constructs that are
expedient in the short term but that set up a technical
context that can make a future change more costly or
impossible.

21. — Philippe Kruchten, Robert Nord & Ipek Ozkaya: Managing Technical Debt: Reducing Friction in So
ft
ware Development (2019), p. 5.
“In so
ft
ware-intensive systems, technical debt consists
of design or implementation constructs that are
expedient in the short term but that set up a technical
context that can make a future change more costly or
impossible. Technical debt is a contingent liability
whose impact is limited to internal system qualities —
primarily, but not only, maintainability and evolvability.”

22. Principles of technical debt (Kruchten, Nord, Ozkaya)
1. Technical debt reifies an abstract concept.
2. If you do not incur any form of interest, then you probably do not have actual technical debt.
3. All systems have technical debt.
4. Technical debt must trace to the system.
5. Technical debt is not synonymous with bad quality.
6. Architecture technical debt has the highest cost of ownership.
7. All code matters!
8. Technical debt has no absolute measure neither for principal nor interest.
9. Technical debt depends on the future evolution of the system.

23. Principles of technical debt (Kruchten, Nord, Ozkaya)
1. Technical debt reifies an abstract concept.
2. If you do not incur any form of interest, then you probably do not have actual technical debt.
3. All systems have technical debt.
4. Technical debt must trace to the system.
5. Technical debt is not synonymous with bad quality.
6. Architecture technical debt has the highest cost of ownership.
7. All code matters!
8. Technical debt has no absolute measure neither for principal nor interest.
9. Technical debt depends on the future evolution of the system.
Technical debt is omnipresent, concrete, context-dependent and the e
ff
ect of (non-)choices.

24. Intentional debt
You choose to take a shortcut and repay it later

25. Intentional debt
You choose to take a shortcut and repay it later
Unintentional debt
You do something resulting in it being hard to deliver value

28. “Technical debt landscape” (based on Kruchten, Nord, Ozkaya)
Maintainability
Evolvability
The future Right now
Visible Visible
Mostly invisible
Code complexity
Code smells
Low internal quality
Structural complexity
Architecture smells
Pattern violations
New features
Additional functionality
Defects
Low external quality

29. Naturally accruing technical debt
Maintenance: Natural complexity and change over time
Evolution: Changes and features introduced
We can control the maintenance curve!

30. “Wine ages, so
ft
ware rots.”

31. It’s unprofessional and unethical to
accept your so
ft
ware becoming worse
over time.
An attitude change is required from us

32. — Kent Beck, “Friction” >> “Debt”
Make it easier for stakeholders to understand how debt a
ff
ects your work

33. — Kent Beck, “Friction” >> “Debt”
“It’s not what you say; it’s what they hear. Many business folks hear
‘mistakes’, ‘delay’, and ‘no progress’ when they hear ‘technical debt.’ […]
Make it easier for stakeholders to understand how debt a
ff
ects your work

34. — Kent Beck, “Friction” >> “Debt”
“It’s not what you say; it’s what they hear. Many business folks hear
‘mistakes’, ‘delay’, and ‘no progress’ when they hear ‘technical debt.’ […]
I’ve begun using ‘friction’ when talking to business folk. We want to
reduce friction in development. I’m talking about the same activities,
the same structural investments, as when I talked about ‘reducing
technical debt’, but I’m using di
ff
erent language. What I like about the
friction metaphor is it implies that we are continuing to move forward.”
Make it easier for stakeholders to understand how debt a
ff
ects your work

35. An action plan

36. An action plan
1. Define technical debt and make it a shared understanding.

37. An action plan
1. Define technical debt and make it a shared understanding.
2. Run a survey in your team(s), asking the software engineers how much they estimate they spend on the effects of technical debt today.

38. An action plan
1. Define technical debt and make it a shared understanding.
2. Run a survey in your team(s), asking the software engineers how much they estimate they spend on the effects of technical debt today.
3. Gather hard data from your version control system, CI/CD systems, and ticket systems.

39. An action plan
1. Define technical debt and make it a shared understanding.
2. Run a survey in your team(s), asking the software engineers how much they estimate they spend on the effects of technical debt today.
3. Gather hard data from your version control system, CI/CD systems, and ticket systems.
4. Quantify the cost of the current state.

40. An action plan
1. Define technical debt and make it a shared understanding.
2. Run a survey in your team(s), asking the software engineers how much they estimate they spend on the effects of technical debt today.
3. Gather hard data from your version control system, CI/CD systems, and ticket systems.
4. Quantify the cost of the current state.
5. Run a problem-oriented technical debt review, such as the HealthCheck, to identify, quantify, prioritize, and assign debt items with clear
resolution criteria to people who can take concrete actions to solve the issues.

41. An action plan
1. Define technical debt and make it a shared understanding.
2. Run a survey in your team(s), asking the software engineers how much they estimate they spend on the effects of technical debt today.
3. Gather hard data from your version control system, CI/CD systems, and ticket systems.
4. Quantify the cost of the current state.
5. Run a problem-oriented technical debt review, such as the HealthCheck, to identify, quantify, prioritize, and assign debt items with clear
resolution criteria to people who can take concrete actions to solve the issues.
6. Add tooling such as static code analysis to catch, inform, prioritize, and help improve your codebase by automated means.

42. An action plan
1. Define technical debt and make it a shared understanding.
2. Run a survey in your team(s), asking the software engineers how much they estimate they spend on the effects of technical debt today.
3. Gather hard data from your version control system, CI/CD systems, and ticket systems.
4. Quantify the cost of the current state.
5. Run a problem-oriented technical debt review, such as the HealthCheck, to identify, quantify, prioritize, and assign debt items with clear
resolution criteria to people who can take concrete actions to solve the issues.
6. Add tooling such as static code analysis to catch, inform, prioritize, and help improve your codebase by automated means.
7. Address process failures, inside and outside of the software delivery team.

43. Next up:
Practical deep dive

44. 1/4: Practices 👫

48. — A. Tornhill & M. Borg (2022): Code Red: The business impact of low code quality
"Our results indicate that improving code quality could
free existing capacity: with 15 times fewer bugs, twice
the development speed, and 9 times lower uncertainty
in completion time, the business advantage of code
quality should be unmistakably clear."

51. Relationship to testing
- Tests help explain the functionality of a system
- Hard to change something that is lacking tests
- Michael Feathers: “Legacy is code without tests”
- Recommendations:
- What’s the simplest way to gain provable confidence?
- TBD or at least full test automation
- Do not accept flakiness
- Do not accept x % of failing tests
Code
Tests?

52. Relationship to refactoring
- “Broken windows theory” but for code: The “boy scout rule” or “campfire rule”
- Refactoring is about continuously improving the system, without changing the behavior
- Recommendations:
- Internalize and naturalize refactoring in the daily work
- Pair/mob programming or asynchronous reviews
- Skills boost? “5 minutes or less” on GitHub
https://github.com/mikaelvesavuori/5-minutes-or-less-refactoring

53. 2/4: Analysis 🔬

54. Assess the current state (unintentional debt)
- Technical documentation, such as READMEs?
- High level documentation, such as on Confluence?
- Structured comments?
- Automated tests?
- CI/CD?
- Observability?
- Processes (manual) and coordination, syncs…?
- Support tickets?

55. HealthCheck review template

56. Technical debt inventory

58. Codescene

60. Gitmetrix

61. Codemetrix

62. GitAnalyzed

63. GitAnalyzed
233 package.json
142 package-lock.json
115 README.md
74 build/index.js
[...]
Added lines: 738210
Removed lines: 671364
596 Sam Person
81 Dat Person
59 Hoo Person
7 Bot Person
[...]
10 Sam Person,Dat Person,Hoo Person, README.md
7 Sam Person,Bot Person, package-lock.json
3 Sam Person,Dat Person, bin/frameworks/errors/errors.ts
1 Dat Person, bin/entities/BigThing/index.ts
[...]
Churn rate: 4 changes per day
Bug fixes/errors: 79 out of 817 commits (9%)
main
long-living-branch-that-we-need-to-get-rid-of
develop
nasty-integration
Days since the last commit: 6
File Churn
Code Ownership
Author Churn
Churn Rate
Active Branches
Days since last commit
Bug
fi
xes
Line Churn

64. Generated so
ft
ware architecture graphs

65. src
application
services
utils
domain
fitness-functions
services
infrastructure
aws
utils
io
math
string
time
FitnessDataService.ts
getAPIGatewayErrorRate.ts
getAPIGatewayRequestValidators.ts
getAPIGatewayRESTInstances.ts
getDynamoDBTableInfo.ts
getDynamoDBTableNames.ts
getDynamoDBUtilization.ts
getEC2Instances.ts
getExposedDatabases.ts
getFargateTasks.ts
getLambdaFunctions.ts
getLambdaTimeouts.ts
getPublicS3Buckets.ts
getSpend.ts
getTaggedResources.ts
isArchFitTestName.ts
FitnessDataStore.ts
createMetricDataCommand.ts
getRDSDatabases.ts
getECSClusters.ts
reduceToValue.ts
getS3Buckets.ts
shortDateStartOfPeriod.ts
shortDate.ts
isCurrency.ts
APIGatewayErrorRate.ts
lessOrEqual.ts
toPercent.ts
value.ts
APIGatewayRequestValidation.ts
moreOrEqual.ts
customTaggedResources.ts
dynamoDBOnDemandMode.ts
dynamoDBProvisionedThroughput.ts
withinTolerance.ts
lambdaArchitecture.ts
lambdaDeadLetterQueueUsage.ts
lambdaMemoryCap.ts
lambdaRuntimes.ts
lambdaTimeouts.ts
lambdaVersioning.ts
publicExposure.ts
ratioServersToServerless.ts
spendTrend.ts
daysInCurrentMonth.ts
daysPassedInMonth.ts
firstDayOfCurrentMonthShort.ts firstDayOfMonth.ts
ArchFit.ts
writeFile.ts
index.ts
exists.ts
readFile.ts
checkForRequestValidation.ts
daysToSeconds.ts
pastDate.ts
test.ts
Generated so
ft
ware architecture graphs

67. Dorametrix

68. github-dora-metrics

69. Output from this phase
- Identified technical debt, including exact locations of it, using manual and tool-assisted means
- Prioritized technical debt activities
- Understood current delivery and feedback cycles
- Huddled together to identify and work on improving technical practices and process improvements

70. 3/4: Technical foundation 👩💻

71. Solid foundation of static analysis and automation to automate away unintentional debt
🐶

72. Example of TypeScript con
fi
guration

73. Example of ESLint con
fi
guration

74. Output from this phase
- Introduced tools and automation to remove consistent points of errors and non-value adding chaff
- Shift left on security and compliance-related activities, such as generating SBOMs, diagrams, docs, and more
- Better developer experience and higher rate of feedback; more productive

75. 4/4: Corrective standards ✅

80. StandardLint
✅ PASS: Diagrams
✅ PASS: Changelog
🛎 No custom path assigned to check "Diagrams" - Using default path "diagrams"...
⚠ WARN: Diagrams
✅ PASS: Lock files
✅ PASS: License
❌ FAIL: Code owners
❌ FAIL: Contribution information
🛎 No custom path assigned to check "IAC configuration" - Using default path "serverless.yml"...
✅ PASS: IAC configuration
🛎 No custom path assigned to check "SLOs" - Using default path "manifest.json"...
⚠ WARN: SLOs
🛎 No custom path assigned to check "Tags" - Using default path "manifest.json"...
✅ PASS: Tags
🛎 No custom path assigned to check "CI configuration" - Using default path ".github/workflows/main.yml"...
✅ PASS: CI configuration
✅ PASS: Security information
🛎 No custom path assigned to check "Service metadata" - Using default path "manifest.json"...
✅ PASS: Service metadata

81. ArchFit

82. Output from this phase
- Homogenize expectations of software in terms of architecture, composition, and compliance
- Enforce standards beyond the basics, moving into software architecture
- Able to programmatically determine fitness of architectures and implementations

83. One more thing: AI bonus!

86. 🙇 Thank you!

87. References and resources
- Mikael Vesavuori: From Technical Debt to Technical Health with HealthCheck:
https://medium.com/better-programming/from-technical-debt-to-technical-health-with-healthcheck-3e7fdc132f58
- Kent Beck: “Friction” >> “Debt”: https://www.mechanical-orchard.com/post/friction-over-debt
- Philippe Kruchten, Robert Nord & Ipek Ozkaya: Managing Technical Debt: Reducing Friction in Software Development:
https://www.oreilly.com/library/view/managing-technical-debt/9780135646052/
- Stripe: The Developer Coefficient: https://stripe.com/files/reports/the-developer-coefficient.pdf
- Codescene: Business costs of technical debt: https://codescene.com/hubfs/calculate-business-costs-of-technical-debt.pdf
- Raygun: How much could software errors be costing your company?: https://raygun.com/blog/cost-of-software-errors/
- Terese Besker: Technical Debt: An empirical investigation of its harmfulness and on management strategies in industry:
https://research.chalmers.se/publication/518318/file/518318_Fulltext.pdf
- Martin Fowler: Is High Quality Software Worth the Cost?: https://martinfowler.com/articles/is-quality-worth-cost.html
- Frederick P Brooks Jr.: No Silver Bullet: http://worrydream.com/refs/Brooks-NoSilverBullet.pdf
- https://testing.googleblog.com/2020/08/code-coverage-best-practices.html?m=1
- https://refactoring.guru/
- https://code.visualstudio.com/docs/editor/refactoring

88. References and resources
- https://codescene.io/
- https://eslint.org/
- https://www.checkov.io/
- https://trivy.dev/
- https://www.archunit.org/
- https://github.com/ts-arch/ts-arch
- https://github.com/anchore/syft
- https://github.com/typicode/husky
- https://github.com/sverweij/dependency-cruiser
- https://arkit.pro/
- https://snyk.io/
- https://prettier.io/
- https://marketplace.visualstudio.com/items?itemName=nicoespeon.abracadabra

89. References and resources
- HealthCheck review: https://docs.google.com/spreadsheets/d/18uoetVewKqLgwOBw8l256eT0aLIFoJyWdo2IE_ZbAHg/copy
- Tech debt calculator: https://docs.google.com/spreadsheets/d/1DPlQyDw5qmt9MegA5m8voIt7p93wzDDoTqOQ2rnHNKw/copy
- https://github.com/mikaelvesavuori/5-minutes-or-less-refactoring
- https://github.com/mikaelvesavuori/archfit
- https://github.com/mikaelvesavuori/minion
- https://github.com/mikaelvesavuori/standardlint
- https://github.com/mikaelvesavuori/codemetrix
- https://github.com/mikaelvesavuori/dorametrix
- https://github.com/mikaelvesavuori/gitmetrix
- https://github.com/mikaelvesavuori/gitanalyzed
- https://github.com/mikaelvesavuori/github-dora-metrics
- https://github.com/mikaelvesavuori/chatgpt-architecture-coach
- https://github.com/marketplace/actions/license-compliance