Speaking as a developer who has probably violated every convention on the list, I think this idea makes a lot of sense, and I think this list nicely sums up all the issues being discussed. Looks like I have a lot of rework to do, so: +1 for being gentle with developers whose modules don't meet these standards : -) Karen ----- Original Message ---- From: Derek Wright <drupal@dwwright.net> To: development@drupal.org Sent: Monday, January 8, 2007 5:25:19 AM Subject: Re: [development] QA: Consensus on comment formatting +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.