Tech Debt Tracker for VSCode
Identify, prioritise, and pay back technical debt with your team, guided by clear metrics.
In today's fast moving world, we have to deliver software quickly and adapt to customer needs. But this means codebases accumulate cruft and code becomes increasingly difficult to modify.
This extension helps you and your team identify and discuss how to incrementally improve the health of the codebase while delivering important features.
These improvements quickly compound to make you much more productive.
💃 Your code is analysed locally and doesn't leave your machine 🕺
This is an early release. If it's not running smoothly for you, please don't hesitate to reach out via our support page.
Table of contents
How it works
The extension helps you identify, discuss, and prioritise tech debt as you explore your codebase.
Identify tech debt
Inline debt ratings, the debt ratings tree, and the function metrics keep quality front of mind. Every function is analysed live & locally to help you write clean code and identify code that needs to be improved.
Discuss & prioritise refactoring work
The metrics are only here to guide you. You and your teammates are best placed to prioritise improvements with simple impact / effort votes and discuss the improvements you'd like to see.
Pay back tech debt that matters
The more your team uses the extension, the better it gets: you easily create a prioritised backlog of improvements together. Some improvements are quick wins and can be done whenever, while others require more careful planning and time allocation.
The debt ratings
Ratings range from A (best) to E (worse). A function rated A is less likely to receive a bug fix in the future than a function rated B, etc.
The debt ratings are computed by an algorithm trained to estimate the likelihood of code receiving a bug fix in the future based on its metrics. This analysis is done on a combination of open & closed source repositories which use semantic commit messages.
We checkout the state of the repositories 2 months ago, parse and rate all the functions, and then look at the commit history since then. We look out for commit messages prefixed with fix: and check which functions were modified by these commits.
This is what gives us the relative likelihood of functions receiving bug fixes in the near future based on their debt rating.
Note that these estimates are just to give you a sense of the impact of badly rated code, they're not meant to be treated as scientific predictions and you should always apply your best judgement. They're likely to change over time because we're continuously expanding our dataset and refining our algorithms.
The code metrics
We've picked a few metrics that are well-known indicators of code that could use cleaning up and that are predictive of bugginess.
These metrics are meant to guide your refactoring efforts and help you determine how to clean up the code. We don't recommend obsessing over them and making sure every piece of code is green with respect to every metric.
Keeping functions small helps write concise, simple code that doesn't do too many things and is easy to understand by engineers who didn't write it.
(Note that for JSX the ranges are 0-39, 40-89, and 90+.)
These thresholds are based on the idea that functions should fit in your head and you should be able to read the code without scrolling.
If a function you're dealing with is too long, try to break it down into simple components that can be combined together.
Limiting the number of independent paths in a function helps write simple code that can be easily understood without having to build a big mental model of all its intricacies. It's also less likely to contain bugs.
These thresholds are based on the Software Engineering Institute report (pages 145-149).
If a function you're dealing with is too complex, try to break it down, de-duplicate code, and wrap functionality that is not directly related to business logic into helper functions.
Functions that are easy to understand can be modified more quickly and with less risk of unwanted side-effects. For this metric, we are using "Halstead Volume" (part of the Halstead complexity measures) which measures how much information a reader of the code potentially has to absorb to understand its meaning.
These thresholds are based on experience and empirical data.
If a function has a high understandability rating, think about how you could simplify it - is it too long, or trying to do too many things?
Functions that take too many arguments tend to do too many things or indicate that a data structure is missing. Try to avoid functions with too many arguments to write readable code that is easy to unit test.
These thresholds are based on experience and various online resources such as this StackOverflow post.
If a function has too many arguments, consider whether you should create a new data structure to hold things that logically belong together. Also consider breaking it down into smaller functions with simpler responsibilities.
Avoiding deep nesting is recommended otherwise code quickly becomes hard to read, reason about, and modify without making mistakes.
These thresholds are based on experience and empirical data.
If a function contains deeply nested code, try unpacking the control flow into simpler bits and reworking the order of the logic to favour early
Heavily commented code is typically full of complexities that have been explained via comments instead of improving the code, and these comments tend to become out of date as the code evolves without comments being updated. It's good practice to write clear code that can easily be understood by the reader without extra information.
This metric is work in progress currently and the categorisation into
Note that given a complex piece of code, it's better to have helpful comments that explain why the code works the way it does rather than no comments at all, everything else being equal. But the real solution is to rework the code so it's easier to understand and doesn't need to be explained. We generally follow these guidelines.
There are 4 configuration options which you can find in the VSCode settings searching for
This is just the first step of a long journey. We've got big plan and we'd love to hear your thoughts on what we should work on next.
Join us on Spectrum to check out work in progress and help us plan our next steps 🙏
Data and privacy
Code metrics and debt ratings
Code metrics and debt ratings are all computed live locally, so your code doesn't leave your machine.
Notes are stored in our cloud backend hosted on Google Cloud Platform. They are stored against identifiers for functions (such as the file & function location in that file), not the code itself.
GitHub account details
We require you to create an account with Stepsize by logging in with GitHub to create shared notes.
This gives us access to your email(s) which we only use for purposes related to the extension and don't share with any third party.
Your repository doesn't need to be hosted on GitHub to use the extension, and the GitHub login doesn't allow us to access your repositories.
Debt ratings feedback
If you send us feedback about a debt rating by clicking on a letter grade for Tell us how you'd rate this function, we will send an Anonymised Abstract Syntax Tree (AAST) to our servers so we can improve our rating algorithm.
You can find an example AAST here – you'll see that all the identifier names have been stripped and none of the code depended on is available. All that remains is the code's structure from which the metrics are derived.
We think this is reasonable and strikes the right balance to empower you tell us how to improve our algorithm without exposing your code.
We plan to make this configurable in the future, but for now if this bothers you please don't send us feedback about the debt ratings.
Extension usage analytics
We are a company trying to build a business and we want to measure how this extension is used and how much it's used, so we track some usage analytics completely anonymously – e.g. whether you've inspect an entity in via the Debt Ratings tree view.
No personal information is tracked and neither is any code.
We simply track events that look like this:
We plan to make this configurable in the future so you can opt out.
Support and community
The easiest way to get support, report an issue, or give feedback is to visit https://terms.stepsize.com/support and talk to us via Intercom (the chat in the bottom right corner).
You can also request features or vote on requested features here.
The best place to get to know us, have a chat, and check out our work in progress is to join our Spectrum community. We'd love to hear from you! 🤗
We are planning to open source the extension code eventually, but for now it's released as unlicensed software.