Todo Comments Discussion

Moved discussion from TodoComments to TodoCommentsDiscussion.

Consider putting your ideas either in TodoCommentsConsideredHarmful or TodoCommentsConsideredUseful.

Two questions:

Are people using TODOs more to leave notes for themselves, or to communicate points to others?
What sort of idea gets TODO status as opposed to being put in some external list? I'm getting the impression that this sort of note is more on the internal design level as opposed to functionality level, though that might be just my misinterpretation.

-- francis

I use TODOs to leave notes for myself. For instance, today I saw three methods that do basically the same thing. I saw this while I was adding a column to a database table and the logic that went with it. If I had stopped to merge those three methods into one I would have lost my train of thought (or at least slowed it down). Instead I left a single TODO comment on one of those methods that said "Merge this with foo and bar."
My external list contains high level change requests and open design issues. My TODO comments contain specific thoughts about the code that came to me while I was in the middle of something else. They are sort of like call backs (or continuations or closures). When the current task is done I work through the TODOs. Eclipse (and other IDEs) create TODO comments when they generate code for classes, methods, exception handlers, etc. Many times I'll let Eclipse generate the code that the compiler needs and ignore the details until I've expressed my current idea. Then I go through Eclipse's TODO comments and fill in the blanks. If I stop to write every constructor and exception handler when I create it I lose focus and have to unwind my mental stack. It's much easier to let the tool manage a stack of those kinds of tasks.

Folks who pair with me sometimes comment that I work "backwards". I write the code I want as if all of the objects and relationships it needs were already in place. The compiler tells me which ones don't exist, so I let the IDE do most of the leg work creating them. I fill in the blanks until the unit test passes. I find this more efficient than plotting it all out ahead of time.

-- EH

We have tried personally addressed TodoComments. If I have a question about a piece of code, (like "Is this how this should be? Shouldn't we frobnicate the foo here?") but the person who knows most about it is not available at the moment, I just write a question prefixed with person's initials and commit it to CVS. Now if everybody has Eclipse configured so that TODOs in his initials show as high-priority tasks, the person will see the message when he checks out code for the next time. It's actually much more convenient than e-mail. This also works great for leaving personal messages for myself as they will show up only in my task-list. -- JuhaKomulainen

You may want to consider using a UnitTestAsTickler instead of TODO comments.

Nice thought, but as it stands, unworkable. That page says "The UnitTests are run before any programmer releases any code to the system configuration, and must run at 100%", and I think that is correct, and essential, regardless of which methodology the organization is following.

TODO comments are, by their nature, an indication of something that should be done later, not now, so they would result in failing unit tests, which is unacceptable, so QED, that's not the way to go.

Several other comments tried to suggest that nothing should be deferred to the future, to make TODOs go away, but a small amount of thought shows that you can't do everything now rather than later, so the only real question is how best to track the various kinds of things that will be done later.

Conceivably you could create something for TODOs like a UnitTest, but which is not an error if it fails, but that seems to be a rather different subject which would require a new methodology.

Oh, wait, I missed the very end of the referred-to page:

"Related idea: If you do use your initials or // TO TO or #needsWork, put a date on the same line. Write a UnitTest that looks for senders of #needsWork, checks the date in the method, and if the date has been passed, fails. UnitTest as Code Monitor"

Is that the part you meant? That's not a bad idea, although it can't work all the time, since one doesn't always know the appropriate due date.

I kind of like this...but to me it doesn't seem like a replacement of TODO, it seems more like adding further automated support for using TODOs -- which I've always liked as a general idea.

I'm strongly against to-do comments. They're a socially-acceptable way of slacking off on GoodDesign. When my pair and I are working on something, I write to-do's on a card. Some of them we do and some of them we toss. Either way, we make the code better today than it was yesterday.If the idea was a good one, someone else will have the same idea and refactor the code later. If that doesn't happen, either the idea wasn't good or the code isn't visited often. Either way, it's better that we didn't spend time on it. --JimShore

Why is writing TODOs on a card a less socially-acceptable way of slacking off on good design than writing them in the code? -- EH

They're a socially-acceptable way of slacking off on GoodDesign.

Totally untrue. It's a way of saying i am working on something more important right now, remember to do this later. If you don't remember that's your fault.