# The annoying TODO tag

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