[development] QA: Consensus on comment formatting
Gary Feldman
dpal_gaf_devel at marsdome.com
Mon Jan 8 18:01:10 UTC 2007
Derek Wright wrote:
> * 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.
Is it correct to read this as: "Convert to HTML" is ok, but neither
"Does the HTML conversion" nor "Do the HTML conversion" is ok?
> * 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.
I believe that even Unicode calls the ' character an apostrophe. The
term "inverted commas" seems like an unnecessary neologism.
Gary
More information about the development
mailing list