[development] QA: Consensus on comment formatting

[Will Moy]

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