[development] QA: Consensus on comment formatting

[Derek Wright]

+1 for for Angie and Nedjo calling for a standard. ;)
+1 for standardizing on @todo, @note, etc as supported by phpdoc/ 
doxygen[1].
+1 for a newline between @param and @return.
+1 for allowing // A little extra clarity.  (as a "1-liner")
+1 for formatting comments like sentences, but not requiring full  
sentence grammar on 1-liners.
+1 for 80 chars wide if possible.
+1 for always referring to DB table names as {foo}, not "foo", 'foo'  
or foo.  Even though it's technically not required as a delimiter  
since the names can't have spaces, i find it adds a lot of clarity to  
quickly be able to tell if a comment is talking about the DB at all,  
and if so, which table(s).


Here's a new draft of the conventions given everyone's input, my  
votes above, and a few other suggestions:


* Comments should be written in English, with correct spelling[2],  
punctuation, and grammar.
* Being concise is best, but never at the expense of clarity.
* Comments are capitalized and end in periods. They should be  
complete sentences on their own line unless they are documenting  
lists, or are describing a line of code that only needs a few extra  
words to be clear. sentences are separated by a single space.[3]
* @file documentation begins with a sentence in present tense, and  
has a blank line before any further comments.
* 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.
* There is a blank line between @param and @return sections in  
function documentation.
* Comments should not use all caps, e.g, NOTE. Instead, use @note,  
@todo, @warning, @bug, etc.
* Any comment that refers to a variable should include the dollar- 
sign in front of the $variable_name.
* Any comment that refers a database table should use {table_name} to  
make it visually unique, not "table_name", 'table_name', etc.
* In general, URLs, code snippets, file names, etc, should not be  
enclosed in quotation marks (") or inverted commas (') unless it  
significantly enhances readability. Where necessary, inverted commas  
should be used rather than quotation marks.
* No comment should be, or cause a line of code to become, wider than  
80 characters.
* In general, comments should not refer to issue node ids (for  
example, "// This is crazy, and we fixed it in #12345."), since  
that's what the CVS annotation and commit logs are for. However,  
links to issues are allowed (recommended?) in a @todo or @bug. In  
this case, a full URL should be used. For example:
   // @todo These queries are very expensive, see http://drupal.org/ 
node/105639.


any final changes/editions/subtractions? ;)

thanks,
-derek


[1] http://www.stack.nl/~dimitri/doxygen/commands.html

[2] i really don't care about "american" vs. "british" spelling.   
english sux, but it's the best we've got. :(

[3] personally, i find 2 spaces between sentences *way* more  
readable, but i've already lost that debate (at least a bunch of  
patches already went into core to force it to 1 space) so i don't  
intend to re-hash that decision.  i'm now in favor of 1 space in  
comments, just for consistency and less work moving forward.