// TODO measure technical debt

I recently started work on a new project, developed by another company. I was initially very pleased to see that the code base was very clean, no TODOs or FIXMEs anywhere in the code. This is in stark contrast to pretty much every project I have worked on over the last 20 years or so which have included TODOs and FIXMEs. Lots of them!

A quick inspection of the code though showed there were plenty of places that needed them. There was some dubious code, some code that needed to be revisited and some code that needed some discussion amongst the team. These issues though were all hidden and only became apparent by reviewing the code, trawling through each function to see what was where. Luckily the code base for the project was relatively small so was doable.

Given that most, if not all software has questionable areas then where is the best place to record this and how is it best recorded?

The answer, in the code itself.

That’s what comments are for.

Not just comments though, semantic comments. Marked up and annotated comments. Machine readable comments. Machine understandable comments?

Before getting too carried away – what are we talking about? The simple TODO and FIXME. When adding one of these you are tagging the comment, you are giving it meaning. In effect you are adding semantics to the comment. So, if you are already doing this – then why not embrace it and take it further?

I regularly use TODOs when I write code. There are lots of situations when writing code where I don’t want to address something there and then, I want to focus on the problem in hand and will insert a TODO as a temporary bookmark to remind myself to come back to it later. These TODOs are meant to be ephemeral, addressed and removed by me before the code is committed to source control. In general, nobody else should see them. Often, they resolve themselves as the code develops and is fleshed out. Occasionally, some do get left behind and sometimes they get left in intentionally to be sorted at some future date.

Some example TODOs:

// TODO need to think about what happens when value is null

// TODO sort out the i18n

/* TODO log */

// TODO not implemented yet

// TODO optimise

A FIXME is different. These tend to get put next to code that you know is not right. It is more serious. It is not something that has been overlooked, this is something that somebody has made a conscious decision as not being right. These should really be addressed, or at least recorded and planned in to be addressed at some point in time or if appropriate downgraded to a TODO.

Some example FIXMEs:

// FIXME take out the thread sleep

So, what else is the TODO or FIXME doing? It can be regarded as a bookmark to code that is not quite right, not yet finished, or is questionable in some way. All of these can be regarded as technical debt – hidden issues in the code that need some resolution. So, if that is what they are unconsciously being used for then why not make it explicit and use them for this.

• Mark up your code – add your TODOs and your FIXMEs.
• Own them. If you add a TODO or a FIXME own it – take responsibility for it – put your name against it.
• Annotate the TODOs and FIXMEs in a consistent way. Define the format in your project development guidelines.
• Measure the TODOs as part of the build process. IDEs (Eclipse for example) lists TODOs and FIXMEs as tasks to complete. For Java projects Maven can generate a site report that includes TODOs and FIXMEs. For Java there is also a CheckStyle TodoComment module.
• Use metrics at build time to generate statistics. This is now a simple (maybe over simple) measure of the technical debt in your codebase.
• Analyse your metrics. Record the number over time. Who is the worst culprit? How old is your technical debt? What is the age profile of your debt?

What should a TODO or FIXME look like? Consistency? Add some metadata. I would suggest keeping it simple and readable, something where the metadata can be extracted using regular expressions perhaps? CSV is old but it works:

// TODO (pillingworth, 12/03/2019) need to think about what happens when value is null

You could take it further, JSON just about works but is not so friendly in your code base. You also don’t want to add more overhead by having to validate your TODOs!

// TODO { “author”: “pillingworth”, “date”: “2019-04-28”, “description” : “need to think about what happens when value is null” }

Most tooling provides some level of support for TODOs and FIXMEs. In the Java world Eclipse will list them in a Tasks view. With Maven it is possible to generate a similar report using the site goal and the taglist-maven-plugin.

This could be taken much further by extracting the numbers from the reports and building time based graphs to track how your TODOs and FIXMEs change over time.

You should find that by accepting what you are already doing and formalising it, then adding in some reports to the build process you now have a better measure of one aspect of the technical debt in your code base.

 

 

By Paul Illingworth