Code Advice #2: No Vanity Tokens

WARNING: This blog entry was imported from my old blog on blogs.sun.com (which used different blogging software), so formatting and links may not be correct.

(See intro for a background and caveats on these coding advice blog entries.)

Some programmers like to tag their code modifications with their
own initials:

//!FB Shouldn't we compare with MIME type?

I've been told the format shown here, using the explamation
point in front of the initials, is/was the preferred format
at Borland. They even had a tool to go and strip these
types of comments out before releasing source code to customers.

Having people "sign" their comments doesn't contribute to
make the comment more readable. Real projects should be using
some kind of version control system, and information about
which line was written by whom (as well as when)
belongs in the version control system, not inline in the source.
The comment should be able to stand on its own feet.

There are some standard tokens that should be used.
TODO, FIXME, and XXX are
standard tokens used to mark code that needs to be revisited.
They are "standard" in the sense that many editors and IDEs automatically
highlight and search for these tokens. In fact, they are even
documented in section 10.5.4
of the standard Java code style document:

Use XXX in a comment to flag something that is bogus but works.
Use FIXME to flag something that is bogus and broken.

They left out TODO, which should be used where something hasn't
been implemented in the first place.

By the way, @todo is a reserved javadoc tag and
means the same as TODO in comments. (Speaking of javadoc tags,
@author is obviously okay and does not fall under the no-vanity-tokens
guideline.)

In addition to these, I use some additional tokens to mark code
for other purposes:

• 
  JDK15 is a token I attach next to code or comments
  which should be revisited when we drop JDK 1.4 support and can
  start using JDK 5.0 APIs. For example, I have code in the designer
  which tracks the current mouse position (such that pressing Ctrl-V
  to paste a component from the clipboard places it under the mouse
  position). In JDK 5.0 there is a new API which lets me look up
  the mouse pointer position directly (yay!! Thanks!) so I can rip
  out the old-style code.
  
  
  


• 
  NOI18N is a code marker which indicates that any String
  literals on the same code line are deliberately not internationalized.
  This is used for Strings which not be localized, such as the name
  of a Java class used in Reflection-related code for example.
  

I'm sure there are other useful tokens too. What makes these different
from "author signatures" in comments is that they are added specifically
to facilitate locating this code fragment in the future (when looking
for JDK 5.0 migration possibilities for example) or for processing
by tools (such as the String localization checker).

Including bug ids in comments falls in roughly the same category.
Code segments full of bug database numbers are hard to read. It's much better
if the various corner cases that were exposed by bugs are explained
inline in the code. This is less of an absolute however in cases
where there truly is a lot of value for a developer to be able to
look up associated bug reports and history.
And of course, code which was added as a specific workaround for
a bug elsewhere (such as a OS or JDK bug) should have the associated
bug id included, such that future developers can look up the status of
the bug and easily determine if the code is still necessary.