TODO-based Development

(Day 4 of 30 Days of Blogging)

I use TODO comments a lot when working on small projects. Projects where the “issue tracker” is just a text file in my editor, and mainly to stub out empty methods that I’ll implement later. TODOs are easy to insert, and they move with the source code. The main drawback is that they usually get lost and end up as bitrot.

Keeping track of TODOs by searching the codebase is pretty straightforward. It can even be integrated nicely in vim:

rg --vimgrep --only-matching '\b(TODO|FIXME)[:;.,]? *(.*)' --replace '$2'

That will present all comments of the form // TODO: fix Y2K bug in vim’s quickfix list.

Even better is if we can sort the TODOs by date:

rg --vimgrep --only-matching '\b(TODO|FIXME)\s*\(([\d-]*?)\)[:;.,]? *(.*)' \
    --replace ' $2 | $3' -- "$@" | sort --field-separator ":" --key 4 --reverse

This requires adding the date inside the comments like this: // TODO(2021-01-04): Implement foobar. Inserting the date can be made automatic in vim by using an abbreviation:

inoreabbrev <expr> TODO "TODO(".strftime("%F").")"

Then whenever you type TODO in insert mode it expands to include the date. No plugins required! If you found this interesting check out the full vim config and the simple todo script it relies on.