[development] QA: Consensus on comment formatting
mcsparkerton at yahoo.co.uk
Sun Jan 7 06:54:18 UTC 2007
IF its a comment that slows down a patch being accepted then I vote -1
IF comment rules reduces the number of comments in code (because its
easier not to comment than to follow the rules) I vote -1
p.s. and since when are all caps e.g. NOTE inappropriate?
"NOTE" says to me "Hey I'm a note! - you should really really read me
because I'm really really important - and you might have lots and lots
of problems if you don't read me"
Angela Byron wrote:
>> So! Anyone have a problem with these rules:
> Gah! I copy/pasted the wrong chunk. :P
> These! :)
> * Comments are full sentences ending in periods, and are on their own
> line unless they are documenting lists.
> * There is no blank line between %param and %return sections in function
> * 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.
> * @file documentation begins with a sentence in present tense, and has a
> blank line before any further comments.
> * Eliminate inappropriate uses of all caps, e.g, NOTE.
> * Spelling, grammar, punctuation corrections.
More information about the development