I really do not like to see the TODO tag in code. It is a sign that the code does less than it promises.
First, I understand the reason for tags like XXX, FIXME, BUG, or BROKEN. Someone has discovered a possible problem in the code, usually long after it was written, and has taken the trouble to warn others. We mark the code with a FIXME because we do not have time to fix it at the moment. An XXX demands attention and is not intended to stay in the code long. We may later decide that no problem exists. Or we may need to document unexpected behavior. If code is broken, we do not expect it to stay that way. We mark the problem immediately so that it is not forgotten.
More often, I have seen a TODO used to justify not completing code at the time it is first written. I have seen whole methods left unimplemented with only a TODO comment as a place holder. Such a TODO postpones part of the project into the indefinite future, when the issues are no longer clear, and perhaps after the original developer is doing something else. Most of these TODOs never go away.
The kind of TODO I fear is a partial implementation. Something was left undone because the author could not decide how to finish it. S/he wanted to move onto something else first. These are just time-bombs waiting for a future maintainer. They steal productivity from the future to make current progress artificially fast. Not knowing how to finish something often means there is something wrong with the design. Feel free to simplify the problem into one you can solve now. Explain what you did, and move on. No one will ever get the impression the code does more than it promises.
Some TODOs simply express a feeling that the original approach is over-simplified. Restrictive assumptions are fine, so long as we document those assumptions. For example, I just saw a TODO saying that a certain kind of ray-tracing used unphysical amplitudes. Instead of a TODO, I would document how amplitudes were calculated and not apologize for it. All kinds of enhancements are expected eventually, and we do not have to predict which ones will be worth doing. When we need something better, we will add it. Again, we just make it clear what the existing code does.
Bill Harlan, Jan 2006
Return to parent directory.