Tech Debt Tracker for VSCode
Identify, prioritise, and pay back technical debt using 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 incrementally improve the health of the codebase while delivering important features. These improvements quickly compound to make your team more productive.
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
Debt ratings of every function and method in your current file are conveniently displayed in the Explorer tree view.
Inspect the real-time metrics behind a function's debt rating in the side panel and add it to your refactoring hitlist if you want to improve the code.
Mark items as completed when you're done improving the code and you're satisfied with the latest metrics.
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 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.
(Note that for JSX the ranges are 0-4, 5-8, and 9+.)
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.
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.
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 complelety 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 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 shortly, but for now it's released as unlicensed software.