Track & pay back tech debt straight from 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.
Your code is analysed locally and doesn't leave your machine.
Currently only supports JavaScript, TypeScript, and Flow.
This is an early release. If it's not running smoothly for you, please don't hesitate to reach out via our support page.
How it works
The extension helps you identify tech debt in your current file as you explore your codebase. Inline debt ratings keep code quality front of mind while you read code and weigh up what to refactor, and the debt ratings tree gives you an overview of the best and worst code in your current file.
When a function catches your eye as a potential thing to refactor, you can inspect its metrics to get a better idea of how to improve it. The extension currently analyses the function's length, complexity, number of arguments, nesting depth, and comment density.
Once you've decided to refactor a function, you can keep track of what you plan to do by adding it to the hitlist, capturing your thoughts, and prioritising it against other code you'd like to clean up.
And finally, when you're done improving the code and you're satisfied with the latest metrics, you can mark hitlist items as completed and focus on the next code to improve!
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.
Function length
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.
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.
Cyclomatic complexity
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.
We use typhonjs-escomplex to compute complexity.
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.
Argument count
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.
Nesting depth
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 returns.
Comment density
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 green / amber / red is a bit complicated. We're working on it and will provide further details shortly.
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.
Configuration
There are two configuration options which you can find in the VSCode settings searching for tech debt tracker:
- You can switch off the inline debt ratings if you find them distracting or don't find them useful
- You can opt in to send non-anonymised feedback on our debt ratings which makes it easier for us to improve our algorithms
Our roadmap
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://terms.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! 🤗
