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.