What is the meaning of #XXX in code comments?
NOTE
: Description of how the code works (when it isn't self evident).XXX
: Warning about possible pitfalls, can be used asNOTE:XXX:
.HACK
: Not very well written or malformed code to circumvent a problem/bug. Should be used asHACK:FIXME:
.FIXME
: This works, sort of, but it could be done better. (usually code written in a hurry that needs rewriting).BUG
: There is a problem here.TODO
: No problem, but additional code needs to be written, usually when you are skipping something.
At least this is how I was taught about these tags. Basically the first two (NOTE
and XXX
) are used for information and no action is required. While the last three (FIXME
, BUG
and TODO
) do require action. HACK
is somewhere in between (and hardly ever used I think?).
Some notes from a June 2005 Python Enhancement Proposal that was rejected.
Choosing between
FIXME
andXXX
is difficult.XXX
seems to be more common, but much less descriptive.
Furthermore,XXX
is a useful placeholder in a piece of code
having a value that is unknown.Thus
FIXME
is the preferred spelling.
Sun says thatXXX
andFIXME
are slightly different, givingXXX
higher severity.
However, with decades of chaos on this topic, and too many millions of
developers who won't be influenced by Sun, it is easy to rightly call them synonyms.
The PEP Starts with,
This PEP has been rejected. While the community may be interested,
there is no desire to make the standard library conform to this standard.
...
What Are Codetags?
Programmers widely use ad-hoc code comment markup conventions to serve as reminders of sections of code that need closer inspection or review. Examples of markup include
FIXME
,TODO
,XXX
,BUG
, but there many more in wide use in existing software. Such markup will henceforth be referred to as codetags. These codetags may show up in application code, unit tests, scripts, general documentation, or wherever suitable.
The PEP is an interesting read.
XXX
in a comment is usually a heads-up. It could be:
- Something that's not implemented completely correctly.
- Something that should be fixed later on.
- Highlighting a possible problem spot.
- Something you're not sure about, a question.
I've often preferred a more descriptive tag like FIXME
or TODO
or HACK
. XXX
is often used as a catch all for the above.
Searching for 'XXX' on the FreeBSD code cross reference is a good example of many of the uses. There are thousands...