[development] QA: Consensus on comment formatting

[Angela Byron]

On 7-Jan-07, at 9:05 AM, Doug Green wrote:

> -1 for proposal, +1 for some guidelines
>
> I'm for:
>
> * Full sentences and sentence capitalization for comments that  
> stand by
> themselves, such as the header /* */ comments and larger asides on  
> what's
> going on
> * For C++ style comments that stand on a line by themselves, Full  
> sentences
> not required, but capitalization is
> * For C++ style comments that are part of another line, anything goes

If you look at Nedjo's patch, the "full sentences" is purely about  
the format of the comments, not subject-predicate agreement. For  
example:

-// Clean up
+// Clean up.

I agree we shouldn't have to write:

// Now, clean up the various variables related to the cron job.

But, it just looks really sloppy to have comments like:

// Clean up
// clean up
// Clean up.
//clean up .

... all over the place. We should pick one way of formatting and  
standardize on it, and "space after the comment delimiter, starts  
with capital letter, ends in period" is the most consistent.

> * All caps is OK for some predefined important names such as.  But  
> these
> should always be followed by full sentences and sentence  
> capitalization.  I
> think we should standardize what these names are (NOTE/WARNING/ 
> HELP), so one
> could easily grep for them.  I use NOTE and WARNING a lot.  HELP  
> could be
> pretty useful in an open source community project for people to  
> point out
> parts that are broken and need some help.  I also use KLUDGE  
> (others use
> HACK), although I'm less tied to this.

Sure, I could go either way on this. NOTE, TODO, etc. are handy clues  
that you should pay attention. Core just was using "Note:" in some  
places and "NOTE:" in others, so Nedjo was trying to find a  
consistent way to show this. I think as long as caps aren't used  
excessively, this is fine for a few keywords.

-Angie