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 and discuss tech debt as you explore your codebase.
Inline debt ratings keep code quality front of mind while you read code and weigh up which functions to refactor, and the debt ratings tree gives you an overview of the best and worst functions in your current file. Both indicate when someone on your team has described how to improve a function.
When a function catches your eye for its metrics or open improvements, you can inspect it. The debt rating is broken down into 6 code quality metrics, and your team's desired improvements are listed with context about the state of the code when they were added.
Finally, you can add an improvement to capture your thoughts on how and when to improve the code, or you can improve it now and resolve your teammate's improvement if that's what pushed you to action. The extension tracks all this and makes it visible to everyone.
Metrics and ratings are computed live, locally, so you can always keep an eye on the quality of your changes.
The debt ratings
The debt ratings are computed by an algorithm trained to predict the likelihood of code receiving a bug fix in the future based on its metrics.
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.
This is evolving very fast so stay tuned for more details once our approach has stabilised. We would love your feedback on how we're doing so please don't hesitate to tell us if you think your code should be rated differently (you can do that directly from the extension).
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://stepsize.com/support and talk to us via Intercom (the chat in the bottom right corner).
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.