I think this is very helpful. I have made a few minor comments on the existing proposed rules at the bottom. One other area that is inconsistent is the use of quotes around table names, variables, code snippets, URLs and file names. I suggest that for simplicity and brevity the rule should be: Table names, variables, code snippets, URLs, file names etc. should not be enclosed in quotation marks (") or inverted commas (') unless it significantly enhances the readability of the comment for other developers. Where necessary, inverted commas should be used rather than quotation marks. Hopefully some examples will help people decide what they like. From bootstrap.inc: // they come first, and we return NOT(status) = 0 (allowed). Otherwise, ... versus ... // The use of ORDER BY / LIMIT is more efficient than "MAX(status) = 0" --- I don't think the quotes in the second line make it clearer than the first. * Role ID for authenticated users; should match what's in the "role" table. ... versus ... * The variable table is composed of values that have been saved in the table ... versus ... // We deny access if the only matching records in the {access} table have --- Again the quotes do nothing for me. Where a table name is used several times in a sentence in a block comment, repeatedly quoting "tablename" would look clunky. The third option here at least has technical merit and would be the best way to delimit table names if it is thought necessary, but still seems like overkill. Table names do not contain spaces and so are already delimited. * Authenticated users are always given a 'no-cache' header, and will ... versus ... // All 304 responses must send an etag if the 200 response for the same object contained an etag --- The first is not clearer than the other, assuming a basic knowledge of HTTP. * configuration file is found, return a default value '$confdir/default'. --- To me is is surprising to see a variable in '', and no clearer than leaving them out. Other notes: - I agree with Doug that the full sentences rule could be overkill in some contexts. One example might be single line comments introducing if, else options. - TODO: comments are a common semi-standard where the captilisation is useful. It would be helpful to specify whether TODO should be interpreted as excessive. Alternatively, if an api.d.o like site were planned for contrib, developers could in future be advised to use the doxygen commands @todo, @warning or @note. Sadly @hack is not implemented ;) - An effort to keep lines to 80 characters would be helpful. - On grammar, is it fair assume the standard is clarity to another English-speaking developer (e.g. there and their)? If I want to start a comment with a conjunction, (such as before an else{}) that shouldn't be an issue. - Might be worth mentioning that Drupal documentation should use US spellings ('color' rather than 'colour').