Code Advice #2: No Vanity Tokens

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

Comments:

Post a Comment:
Comments are closed for this entry.
About

Tor Norbye

Search

Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today