[development] QA: Consensus on comment formatting

[Darrel O'Pry]

On Sun, 2007-01-07 at 11:39 -0500, 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


It would be nice to stick to phpdoc or phpdoc like formatting.
@todo, @note, @hack... 

.darrel.