What is the distinction between technical debt and future improvement?

I was following the pull request for converting the JavaScript.Client to TypeScript (which is quite insightful), and there’s a decision made there regarding needing to explicitly import test framework parts vs them being globally available when writing tests.

I didn’t want to hijack that thread so I’m asking here. Is this really a case of technical debt, or a future improvement? As a follow-up: What is the definition of technical debt used here?


That’s an interesting question. I’m not going to pretend to know the answer, but my opinion on the matter would be that you incur technical debt when you write code that works, but does not adhere to the principles of coding you have decided upon.

Examples of that could be:

  • The code is all there, but there are no tests or specifications for it.
  • You have not written documentation.
  • XmlDoc, JsDoc, etc. is in place - but incomplete or meaningless for 3rd parties.
  • Your code is fragile because it uses internal functionality of libraries that is not really intended for you to use.

For future improvement, I lean towards the notion of making the code nicer. E.g.:

  • Rewriting the code to be more pretty, and easier to read and understand
  • Splitting up large pieces of logic into smaller re-usable parts so it can be re-used in other places or by other people.

It would be nice to get more examples (or contradicting opinions about mine) from others.

1 Like

I agree with @jakob, those are good examples of distinctions.

Here’s my 2 cents as well:

Sometimes you take on technical debt deliberately due to constraints in the project. You do a shortcut to accomplish something for instance in the timeframe you want. What is then a good practice to avoid too much pain is to make sure the API / interface is well designed (if possible) and then skimp on the implementation for later to return to it.

You could also take on technical debt because one does not really now how it should be, so you do a first stab at it.

In both these cases you’re delivering the software functionality, but they’re not optimally implemented - which is why it becomes a debt, its something you want to payback. Sure, it is an improvement to the codebase, but not necessarily for the end product. Whoever is consuming the software with the debt in it, might not notice any difference - so for them its not a clear improvement. The interface is not just a programmatic interface, could also be that you’re giving it to end users with a nice user interface and the implementation behind being less than optimal. But you got to the abstraction you wanted for the user and they can start feeding back what works and what doesn’t.

1 Like

I use the term technical debt about code that keeps you back in some way - things that you should really attend to so that your solution can be easier to work with in the future. All the things that are not the way they should be, in the best of all possible worlds. The things that make adding new features and improvements harder than they really should be.

The more interesting distinction, to me, is whether the technical debt was incurred knowingly or not - and whether there is an intention to “pay it back”.

The nice thing about incurring technical debt (i.e. not making it perfect the first time) is that you can go faster. You can ignore certain things to reach goals that would be impossible if you did not give yourself the leeway to incur debt. It’ll cost you if you maintain the solution, but like monetary debt it is often well worth it to get to where you need to be.

The excellent thing about technical debt is that you can actually decide not to pay it back. Sometimes you just re-do the entire part (effectively declaring bankruptcy for that thing - you’re not paying it back), or even decide to do without it. This is why it’s totally fine to write non-perfect, messy stuff for your prototypes, proofs-of-concepts and spikes. As long as they are going to go away or be re-done you don’t really care about the future coder working with them - there is no such future coder. The debt is essentially free.

If you leave technical debt in something that you want to maintain, however, you’d better look into paying it down or be fine with the cost to future development.

1 Like