Common comment tags

Question

What common comment tags do you find useful, and how do you use them?

For instance, we standardize on:

//TODO: blah blah //FIXME: blah blah //NOTE: blah blah

We have an IDE plugin that is able to pick these up project wide as a reminder.

Do you use any of these aide memoirs? How do you use them? Are they useful? Do you find there are soon too many of them to be useful? Or do you find they clutter up your code when you never go back and tidy them out?

Answer 1

//HACK: Warning, don't do it this way again...
some bad code goes here

Answer 2

XXX: This code is not yet written

Answer 3

//TODO:
//REVIEW:
//BUG:
//FIX: <bug> <date> <user>

Answer 4

My TODO is a flat file referencing files and line numbers...

Generally speaking I dislike "extemporaneous" comments, and try to limit my commenting to actually describing what's going on (though that shouldn't really be necessary).

I suppose I simply try to limit my commenting period...

Answer 5

I like

//HACK: lorem ipsum

It is for things that work, but clearly need a rewrite...

Also, at my company we use

// TODO(from): (to) lorem ipsum

where from is the name of the person, that put the todo in the code and if the todo is for another developer, his name gets in the to-field... This way it is clear whom to ask if some todo is unclear

Answer 6

Doxygen has

//!@todo
//! Don't forget to remelfarb the flux capacitor

or

//!\todo
//! Don't forget to remelfarb the flux capacitor

whichever you prefer

See here for more on doxygen.

MFC/Win32 seems to have chosen the standard

//TODO

not sure if it flags this as special somehow.

Answer 7

I use //NEXT: for TODO's that aren't gonna make it into this release, with visual studio set up to show them at a lower priority.

Visual Studio 2005 let's you configure them under Options->Environment->Task List.

Answer 8

The most useful is probably TODO, particular in editors that support pulling them together into a list such as Eclipse.

In languages that support annotations a better option might be to define a compile time annotation that emits a compiler warning whenever it runs over a @TODO or @FIXME annotation, so that everyone that works on the project has a better understanding of the state the code base is in without requiring specific support in their editor of choice or a full search of the entire code base.

Answer 9

//BRAG: This is a ray-tracer in LINQ
some particularly elegant code goes here

At a previous company this was a lot of fun. Gave people a chance to highlight code they were particularly proud of.

Answer 10

//BUGFIX: is a handy one.

Answer 11

Tags in comments such as these may be useful for small projects, but on larger projects with more than one developer, they should generally be avoided, as they are too easy to overlook. Use a real bug-tracking program whenever possible. TODO's should be built into a project plan as optional tasks, so their benefit can be weighed. FIXME's should be fixed instead of documented, or at least tracked in a bug tracker. So the only thing left to actually put in comments are actual annotations that help a programmer understand the code he/she is reading, including headers for functions and classes, and variable and algorithm descriptions.

Answer 12

I like //TODO: when combined with R#, since you can use R# to look at what you have left todo using the To-Do Explorer.

Answer 13

I like the form

//TODO(name) - Some comment.

Where 'name' is the person who can give context about what needs to be done here. Most of the time is the person writing the TODO.

Another important thing is to specify when the TODO should be accomplished. For example: 'Remove this after SomeOtherClass is checked in.'

Answer 14

/* XXX: This code coincidentally works, but really needs a look */

/* TODO: We need to get to this whenever we get a chance, this is just a stub or missing features */

/* DEBUG: this is debugging code, and needs to be killed before a production released. */

/* NOTREACHED: kind of outmoded, but still useful sometimes. Indicates that the line this comment is placed on will never be reached (Think usage()). */

I also always use "DEBUG: " as a prefix my print-debugging, so I can find it when I'm done and kill it. I tend to use print-debugging a lot, so this is particularly handy.

Answer 15

Little off topic, but I really like the /*/ comment trick.

/*
Section 1
/*/
Section 2
// */

Section 2 is active, but adding 1 "/" in de beginning

//*
Section 1
/*/
Section 2
// */

Makes section 1 active.

Answer 16

Microsoft tends to use tags like <CONSIDER> ... </CONSIDER> for noting potential optimizations or recommendations for tidying up.

Another one is <SECREVIEW> ... </SECREVIEW> for security review related comments.

Sometimes you'll see "BUGBUG" for items where the developer knows that there is a potential problem or that the code could be cleaned up. Larry Osterman wrote more about this on his blog.