Both Eclipse and IntelliJ IDEA have a really nice feature that I started using (and abusing) without even thinking about it — exactly the kind of low-impedance feature I like best. Both programs will scan through your code for comments containing “TODO” (or whatever other flag you use for reminders). They’ll then collate these comments into a to-do list that you can refer to to remind yourself of things you’ve left unimplemented or half-finished. And unlike all those random notes scrawled on pieces of paper around your desk, it’s a list you can trust.

In my case, a simple TODO list is extra useful for a couple of reasons. I have one of the shortest attention spans possible without warranting a Ritalin prescription, so I tend to do things like leaving a large chunk of code completely empty while I dash off to poke at something shiny, like a minor rendering bug or a new widget. I leave the unit tests empty as well, so that nothing actually fails — conveniently defeating one of the primary purposes of test-driven development. With a TODO list inside the code itself, though, I have an easy way to keep a trail of breadcrumbs, reminding me of things I need to come back to. Also, if the list gets too long, I know that I’ve been letting myself get too scatterbrained and I need to settle down and focus on things for a while. At least until I see more shiny things.

Extracting the TODO list from the code’s comments as opposed to offering some other notepad function also reinforces one of those programmer’s laws that we try to deny, but all know to be true: In any given programming project, the source code is the only trustworthy document. Any design docs, UML diagrams, test specifications, or user documentation that you write is almost certainly inaccurate as soon as it’s written, and is almost certainly going to be inaccurate as soon as you make any changes to the system. This is why everyone has fallen in love with unit testing and test-driven development in the last few years. By bringing your tests as close as possible to the actual source code (by making it part of the source code), you increase its trustworthiness.

Javadoc and other comment-driven tools like XDoclet attempt to do for documentation and system configuration what JUnit has done for unit testing, bringing everything as close to the code as possible. These tools have a rougher time of it, because the information they use is embedded in comments, and compilers have a tendency to ignore comments. On the other hand, IntelliJ actually flags bad @link tags in Javadoc, so it may just be a matter of tools catching up with each other.