Aug 22nd 2023

How I manage Technical debt right from vscode.

Before we dive into this blog I like to point out that I use “mess” and Technical debt ( TD) interchangeably.

I am not going to clarify what Technical debt is as it's a common term and kinda conventional wisdom but If you like to dive into that I suggest you do that before reading this blog

Technical debt is common.

If you have been working on a project for a while, you might know where the messes are ( Parts that have Technical debt ).

It’s like a city in a sense. each city has parts that are well maintained with nice sidewalks and roads and the infrastructure well kept but when you stay a while and look around new places you find parts of the city with a messy sidewalk, bumpy roads, and even worse dangerous hoods to live in. you usually know the latter after living for in the city for some time.

Getting back to my topic You want to fix these messes But you might not have enough time or they are used in many places making it hard to fix them (at least related ones). So you just leave them there and hope you will fix them later. spoiler alert You never do.

But those messes spread like wildfire. even (Andrew Hunt and Dave Thomas authors of the PP(Pragmatic Programmer)) explain this in a broken window glass analogy. once a building in a neighborhood has a broken window glass the neighborhood starts to have multiple broken window glasses all over and before you know it it's a messy neighborhood ( it becomes a bad part of town). If you leave the mess alone, it won’t clean itself even worse it will make your whole codebase even messier.

As one of my programmer friends said “I write code that looks like the code around it” and I think every developer does this at some level.

After dealing with a lot of the above issues I came up with a method that worked best for me before explaining that let’s talk about what makes TD hard to track and fix.

Why is dealing with Technical debt hard?

Going back to the broken window glass analogy - you want to fix broken glasses before another broken glass appears in the neighborhood ( if you have a couple of them that is ).

If you have multiple broken glasses you are not only going to fix those that are broken now but also windows that are going to be broken soon( trust me they are coming )

enough with the analogy so What I am saying is once you have a messy code someone might write a code that looks like it ( messy) so you need to fix it ASAP before another one pops in because as we all know development never stops.

But this is not realistic we don’t usually have time and you might be even at a stage where you have many messes in your code already, so what shall you do in these cases?

Proposed solution

Here is what I am proposing comes in, put a yellow tape around it!

Yep, I am suggesting putting yellow tape around the broken window glass implying you are planning to fix it soon.

If you can’t fix it now, communicate with other developers that this is a mess and you are planning to fix it soon, Other developers will see the yellow tape ( a TD comment ) and won’t adapt it at least or in some cases fix it in the process.

This idea is not new you are already using this in your code (e.g. TODO comments ), also experimental flags as well, You ship products that are not yet finished ( not tested properly or might have bugs) but you ship them with an experimental flag well because feedback is valuable.

But why label it, why not just fix it?

Fixing a mess (Refactoring) is not easy

Refactoring a bad code starts with identifying bad code before doing the actual work. it's not a good idea to refactor one part of a related code and leave the other untouched. On top of that, you have to work in teams. Working in teams is particularly difficult because you might not be the one who needs to clean the code, as the other members are responsible / more equipped to do the cleaning but communicating is hard. You have to give line numbers and file path and how do you track if it's fixed? aah, the classic refactoring myopia. It is easier when you think about easy and small stuff but when it gets bigger and complex that is when it gets fuzzy

But wait we don’t want to refactor all bad code, There are codes that severely need refactoring while others we can even leave for later but you are the one who knows the level of TD a code has ( as you are the developer ) so you don’t only need to communicate but also prioritize, hmm

Fortunately, you can set the severity ( priority ) of the

TD comment

  • aha That way you can decide as a team you want to clean up only severe technical debts.

That is cool but what about related parts among different files? because refactoring usually encompasses different files and you want to combine/clean up related files.

For example, let’s say you want to clean up user management - that is huge (takes a lot of effort and time to refactor ) but you want to break it down and fix profile management instead. But wait the code is all over the place, how do you deal with that? hmm…

ahh the

TD comments

has support for labels. It can be anything you like to help you relate related code - it could be a sub-feature / any other way you prefer

Save your tears for another day

Putting a

TD comment
doesn’t relieve you of the responsibility to refactor, You still need to refactor but next time that is but will that day come? Hopefully yes but for now maybe you can start by making a task in your project management tool and keep it in the backlog.

aha grouped labels need to be related to a task - but that is for later we don’t have support for that yet but on the pipeline

But How do I use

TD comments
And what are they?


TD comments
are just comments in your code as the name implies. they have a certain structure to help discover them from your code and help analyze them.

td-manager gif

Each label has a

  • Label - which states the name for a technical debt, you can name this with a specific feature, for example, if you are refactoring som …. [finish]
  • Level - specify the severity/priority of the technical debt - 1 being the least and 5 the highest
  • Message - in the message you can describe why you put the comment and anything you want to say

So how do we use it

When I first wanted to build this tool I wanted a VS-Code extension that scans my code of TD and shows me where with a little stat so that is basically what I have now but I also see a use of this tool using a CLI tool or other IDEs as well

But as of this writing, you can install the extension from here

Here is a little animation to show you how things work

Try it

Try to use the extension if it makes sense for you and I would love to get feedback from developers as well since this is FOSS you can also contribute to it Here is a GitHub link

Hello fellow developer 👋🏾

Looking for expert assistance with your web application development or code review?

Feel free to send me a message or email to discuss your specific needs