[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.


More information about the development mailing list