views:

598

answers:

17

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?

+3  A: 
//HACK: Warning, don't do it this way again...
some bad code goes here
John Meagher
A: 

XXX: This code is not yet written

Daniel Papasian
A: 
//TODO:
//REVIEW:
//BUG:
//FIX: <bug> <date> <user>
Darren Kopp
You should break these out into separate answers so they can be individually voted on.
Portman
;-) Hey, just doing what the Godfather told me to do: http://www.joelonsoftware.com/items/2008/09/15.html
Portman
not asking what the most popular tag is, asking what tags people use. so instead of polluting the answer pane, i'll stick to one answer,
Darren Kopp
absolutely, I was trying to avoid a poll - very informative so far
reefnet_alex
+1  A: 

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...

Josh Wright
A: 

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

Mo
+2  A: 

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.

Doug T.
+3  A: 

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.

Joel Coehoorn
A: 

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.

Orclev
A: 
//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.

Portman
Sounds like agony to me...
Richard Ev
A: 

//BUGFIX: is a handy one.

So you add a comment that simply states that the code below fixes a bug that existed at some point in the past?Seems like this would only make it harder for future code maintainers.
Richard Ev
No, I add a comment for workarounds needed by bugs in unintuitive interfaces to third party code and quick workarounds. In hindsight, I see that this may not be as self-explanatory as I first thought, though.
+2  A: 

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.

deemer
this is a very good point. we do also use bug tracking on all projects. early on in the project I liked the TODOs for very quickly flagging things up while it was all still fluid, but I am seeing quite a few left in now. Mind you, fixed some tonight, so I'm still in two minds about them.
reefnet_alex
If you're using C/C++, you could use #warning to keep them visible in the build log. Even better would be to agree to treat warning as errors at a certain milestone in the project.
deemer
A: 
Mark T
+1  A: 

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.

MagicKat
A: 

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.'

Alejandro Bologna
A: 

/* 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.

Brian Cully
your debug comment is interesting. we always put debug prints hard up against the left margin in indented code so it's easy to spot by scanning down the left margin - but I like the DEBUG prefix idea!
reefnet_alex
+3  A: 

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.

Bob Fanger
@Bob Fanger: nice trick! I would have used a much simpler `#if 0 ... # else ... #endif` though. The toggling happens by changing `0` to `1` or vice-versa.
Lazer
A: 

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.

Jeff Moser