I'd like to share with you a simple approach to making code comments work better. I am a firm believer in applying common sense to comments, so I sit between the guys who say that the good code should be self-documenting and those who claim that comments are an art on their own. For now let's assume that a bit of comments is good in any quantities.
Often it is necessary to put a delayed call for action into a comment, of different strength and purpose. A simple example is you want to delete that piece of code when debugging is done. It would be natural to put a reminder comment there. But the problem is the comments are hard to use as a call for action because they are, umm, just comments. Compare "I think this ship is sinking" and "Abandon the ship!" Also, it is often necessary to "prioritize" calls for action. It may be mandatory to deliver this not yet implemented feature by the release date, but it is OK to look at that one over there when there is time and money.
The coding standard that we have adopted quite some time go to address this issue is this: use a small set of annotations to mark comments that are calls for action. An annotation is just a fixed, agreed in advance, format of the beginning of the comment. My preference set is "TODO:", "FIXME:", "REVIEWME:", "TODELETE:" and "NOTE:". The format we use is this:
// <annotation> - <author> - <date> - <comment>
The annotations speak for themselves:
// TODO - the code yet to be written
// FIXME - fix this part before app goes into production
// REVIEWME - return later and consider a better approach
// TODELETE - delete this piece
// NOTE - this is an extended explanation of decisions lead to this code
A typical annotated comment looks as this:
// FIXME: slava@acme.org - 10/12/2005 - here we just read a property
// from the config file. Should check system property first and return
// it if present.
or
// TODO: slava@acme.org - 10/12/2005 - implement this method. For now
// just return null.
or
// NOTE: slava@acme.org - 10/12/2005 - we agreed (see #704) that e-mail
// notifications that were not sent for any reason are not re-sent but
// just stored in the local file archive.
Using this approach allows having noticeable, and most important, searchable
comments that are calls for action.
Previous Topic
