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? Also, as Robert brought up, // TODO, etc. have support in IDEs (Zend, etc.). Can someone check if @todo does as well? -Angie