[development] QA: Consensus on comment formatting

[Angela Byron]

Excellent! Thanks for the summary, Derek!!


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

Now, just one (technical) question.

Does this:


>   // @todo These queries are very expensive, see http://drupal.org/ 
> node/105639.
>

...actually work and get parsed by doxygen?? I thought doxygen only  
worked on function headers. This would make @todo less useful, imo,  
since:

     // TODO: this can be an expensive query. Perhaps only execute it  
every x minutes. Requires investigation into cache expiration.
     if ($user->uid) {
       db_query("UPDATE {users} SET access = %d WHERE uid = %d", time 
(), $user->uid);
     }

Tells me that the queries immediately following that line are  
expensive, vs.

/**
  * Reads a session variable.
  *
  * @todo the update query used here can be expensive....
  */
function sess_read($key) {

Anyone know?

-Angie