[development] QA: Consensus on comment formatting

[Rob Barreca]

> -// Clean up
> +// Clean up. 
I like the period at the end. Agree on that.

> * Eliminate inappropriate uses of all caps, e.g, NOTE. 
Think we should allow NOTE and WARNING as long as they are used like 
TODOs -- with a capitalized sentence/period. All these are good in my mind.

// TODO: Optimize this query.
// WARNING: Don't do that.
// NOTE: May smell funky.

That is all.

Rob Roy Barreca
Founder and COO
Electronic Insight Corporation
http://www.electronicinsight.com
rob at electronicinsight.com



Angela Byron wrote:
>
> 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
>