Two types of TODO comments

How I use TODO style comments in programming

A recent article from Sophie Alpert about TODO comments resonated with me so I’m writing down some of my thoughts on them as well.

#blog#work#link

I came across a quick post from Sophie Alpert titled TODOs aren't for doing¹ and liked the framing.

I find myself adding TODOs for two reasons:

The first kind are immediate TODOs that need to be done before something will work or be correct. These will always be cleaned up before the code is done.

These are particularly important when I'm working on something and have to put it down. For example on a side-project, I'll always leave a todo: next: ... comment that explains what I was working on and what my train of thought was. This way, even if I don't work on that side-project for the next 6 months, I can pick it up and have an easier time getting into the flow again.

For work projects, immediate TODOs are signals to myself and others working on the project that this part of the code is not working yet. Don't expect this to stay the same or bother testing/reviewing it yet.

The second kind of TODOs are things that could be done, might be investigated, or would be nice, but aren't important to be done today or in the current context/project. These can be unanswered questions or directions to take with the code that isn't important to answer now and was put off.

For instance, if we have an endpoint that returns a nullable string, I might add a TODO next to the field's type definition that says something like todo: can we make this not nullable on the backend?. Maybe just because it'd be a little more ergonomic to not have to check for nulls as much, or maybe because it's a field that shouldn't really be null but might be for historical or esoteric reasons.

These "later or maybe never TODOs" are particularly relevant in business projects where there are outside pressures to ship things, provide value, and get to a "good enough" state instead of a perfect one. These TODOs are less likely in personal projects where I can just take the time to do them right away, but they still show up there.

As a closing note, I understand that lots of people object to comments outright regardless of the type because they get stale. I used to be less keen on comments as a whole in code, but lately I've been coming around to them more. Particularly, they're nice when the can be linked to code (think traceability as defined in the safety critical sector or Rust doc tests) and be automatically checked for accuracy. The TODOs I talked about here don't quite meet that bar though. Maybe we could make them more traceable some day. But this is a topic for another post.