What is the meaning of #XXX in code comments?
CommentsComments Problem Overview
I have seen this a lot in code, even vim marks it as a special case. #TODO
and #FIXME
are two other fix markers vim highlights but what does #XXX
mean?
Comments Solutions
Solution 1 - Comments
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...
Solution 2 - 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?).
Solution 3 - Comments
Some notes from a June 2005 Python Enhancement Proposal that was rejected.
>Choosing between FIXME
and XXX
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 that XXX
and FIXME
are slightly different, giving XXX
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.
Solution 4 - Comments
Have a look at PEP350. It explains all of TODO
, XXX
etc. I use it everyday when I can't remember exactly what one of the code tags means.
Solution 5 - Comments
From (old) Java code conventions:
> Use XXX in a comment to flag something that is bogus but works. Use > FIXME to flag something that is bogus and broken.
Solution 6 - Comments
I use XXX
because it's easier to type than TODO
.
XXX
is for when you're in a hurry and will get back to this yourself.
TODO
is for when you have to hand it off to someone else.
Solution 7 - Comments
Probably it's for cases that you don't know how to handle.
Check out this: List view of TODO/FIXME/XXX/HACK statements
(source: googlecode.com)
Solution 8 - Comments
XXX is short for caveat which is slightly different from NOTE but quite similar to HACK. It may be a bug in a third party library / code which is being used and the code with // XXX: indicates that either it is workaround due to a bug in third party code or it could mean "caution" to someone looking / modifying the code to indicate why something is done in a certain way which otherwise may seem incorrect / inelegant in first look. HACK is generic term meaning a workaround for an issue which could be present in either your own code base or a third party library.
Solution 9 - Comments
I believe while FIXME
is for the developer, and HACK
is for the maintainer, XXX
is for the user.
For example, if you ignore the XXX
and call this function elsewhere, without understanding how it works, something unexpected can happen, and the person dealing with this issue will be unhappy (at least the one who added the XXX
thinks so). You may think the problem will be gone if you just don't use this function.
But for FIXME
, you will feel worthy to just fix the code to make it work. And for HACK
, you may have no better choice even if you don't use it.
If you wrote XXX
on your own code and someone used it, you may feel unhappy for reasons like you completely rewrote that code, and it then behave in completely different ways, and you broke someone else's code. But if you left a FIXME
or TODO
instead, you won't care so much.
Solution 10 - Comments
I use // XXX so I don't have to remember line numbers. Instead I just search for the XXX when I want to return to that piece of code.