[development] QA: Consensus on comment formatting

[Doug Green]

-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
* 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.

For example:

/**
 * This should always be a full sentence and sentence capitalized.
 */
// Not a full sentence, but capitalized
$var = 'something'; // anything goes
// NOTE: Do it this way for performance reasons.
// WARNING: Do not change this.
// HELP: Code below is broken .

My reasoning:

Personally, I use the C++ style comment // more for short- quips about
what's going on, and the C style comment /* */ for larger asides on the
purpose of things. I'm not consistent with this, but I think it would be a
good standard. C++ style comments then are helpful hints as opposed to full
tutorials.

Also, it's nice if the fits on a single line for readability, and I
frequently shorten my comments to fragments for this reason.  A standard
that encourages me to use full sentence structure will result in longer
comments cause lines to wrap, and making them less readable.  (I don't have
an editor that wraps line prettily.)

Doug Green
www.douggreenconsulting.com
www.civicactions.com

Changing the world one node at a time!
-----Original Message-----
From: development-bounces at drupal.org [mailto:development-bounces at drupal.org]
On Behalf Of Angela Byron
Sent: Sunday, January 07, 2007 12:27 AM
To: development at drupal.org
Subject: Re: [development] QA: Consensus on comment formatting

>
> So! Anyone have a problem with these rules:

Gah! I copy/pasted the wrong chunk. :P

These! :)

* Comments are full sentences ending in periods, and are on their own  
line unless they are documenting lists.
* There is no blank line between %param and %return sections in  
function documentation.
* Function documentation begins with a single sentence in the form  
"Do such and such." rather than "Does such and such.", and has a  
blank line before any further comments.
* @file documentation begins with a sentence in present tense, and  
has a blank line before any further comments.
* Eliminate inappropriate uses of all caps, e.g, NOTE.
* Spelling, grammar, punctuation corrections.