[development] QA: Consensus on comment formatting

[Gary Feldman]

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.

Gary