Capture Refactoring Ideas With Annotated TODOs

TODO comments! They're a weird thing to write about maybe, but I've been thinking about them a lot lately.

A "TODO comment" is a comment left in your code intended to (you guessed it!) remind you or someone else of something to do later. Often these comments start with "TODO" or "FIXME", and sometimes they will be highlighted by your editor.

They aren't without a little bit of controversy though. While the intention seems innocent — you can't do everything you'd like right now, so you add a TODO to remind you to come back to it, at the place where the work needs to be done. Critics claim that these TODOs are never actually revisited in practice, fall out-of-sync with the code, and clutter things up (see Todo Comments Considered Harmful).

I think that criticism is entirely fair. Nevertheless, I still really like leaving these kinds of comments in my code. I'm a big believer in refactoring mercilessly. As I'm coding, I'll often think of refactorings that would require changes further up. However, it's usually more important to continue to a working state on the path I'm on. I don't want to forget what and where I wanted to change, so I add a TODO.

That works great if you come back to it, but often you don't get the opportunity. Things change. Other priorities come up. Maybe you get moved to a different team! Now that TODO is someone else's problem.

This is the part where many people start having a problem with them, I think. If a TODO remains in the code, especially after a developer has moved on, did it really need to be done in the first place? The word "TODO" implies it does, but that often isn't the case. Often the comments are a bit cryptic, and are written as a note to the developer themselves.

In order to try and solve this, I've been coming up with a more elaborate "TODO system". I've tentatively called them "annotated TODOs", but really I'm just talking about a set of keywords used to tag and annotate refactoring points in a codebase (if you have a better name, please comment!). Their purpose is to help facilitate continuous refactoring, by more clearly communicating intent from a developer as they make notes in-the-moment, to other developers that may come across the notes later.

That's a lot of talk. Let's look at some details!

First of all, everything should be date-stamped in a consistent format.

// VERB [yy/dd/mm]: message

This is easier to adhere to if your IDE allows setting macros and/or keyboard shortcuts to generate the date. The purpose of dating things is so that we can prune these messages in the future. You need to refactor your comments too!

Some of the verbs I have been using are:

• MUSTDO: This is something that REALLY should be done soon. Maybe you know it needs better error handling, but you've got a deadline and this is just a prototype. Maybe you're not confident in the security aspect of what you've written. Maybe you know something needs to be fixed here before another task can be completed.
• MAYBE: This is just a suggestion of something to do. I've used it to add potential future API methods in pseudo-code inline with the rest of the code.
• STUB: Tag a function as a stub method, to be replaced by something else at a later date. I use this when writing new components in isolation from the rest of the system.
• THOUGHT: You're working on some code, and you have a thought about something you could do with this later. I'm terribly forgetful, so I like jotting down thoughts about what I'm working on, in the place where I'm working on it. I especially don't want to {alt|cmd}-tab to another window.

I've been thinking that all of this might be more powerful combined with some light tracking. Some IDEs can find and track TODO messages in a list for you, however this gets weird quickly with different kinds of TODOs. I think I'd like a way to pull up and sort these comments by type & date, so that they're a bit easier to find and review, as well as easier to prune by date.

That's it I think (for now)! If you're reading this, let me know if you think this idea might be useful to you. Or if you think this is a solution to a problem nobody else has, let me know that too! 🙃

Cheers!