[development] QA: Consensus on comment formatting
dpal_gaf_devel at marsdome.com
Mon Jan 8 18:15:30 UTC 2007
Angela Byron wrote:
> // TODO: this can be an expensive query. Perhaps only execute it
> every x minutes. Requires investigation into cache expiration.
While I agree that there are places for partial sentences, this doesn't
seem to be one of them. Omitting the subject seems to be a popular
shortcut, but it makes the documentation harder to read. It would be
better to write:
//TODO: This can be an expensive query. We should investigate cache
// expiration, and perhaps only execute it every x minutes.
This reminds me of two other points: First, think twice before omitting
a word just to avoid going beyond column 80. Going to a second line
isn't the end of the world.
The second gets back to the issue of quotes or apostrophes. Often, when
you feel a need to put a code fragment or other phrase into quotes, it's
even better to just make it an indented paragraph. However, I wouldn't
be surprised if Doxygen can't handle this properly, so I'm not sure
there should be a rule around this.
More information about the development