Re: [Xen-devel] [PATCH] CODING_STYLE: Allow single-sentence comments without full stops

[George Dunlap <george.dunlap@xxxxxxxxxx>]

On 04/08/16 11:04, David Vrabel wrote:
> On 04/08/16 10:37, George Dunlap wrote:
>> One of the common ways in which contributors trip up over the
>> CODING_STYLE guides is by not putting a full stop at the end of a
>> comment when there is only a single sentence.  Calling these out is a
>> waste of everybody's time: The full stop at the end of a comment with
>> a single sentence (or a single phrase) adds absolutely nothing to the
>> legibility of the code.
>>
>> Modify CODING_STYLE to allow comments with a single sentence or
>> sentence fragment to either have a full stop or not, while making it
>> clear that comments with multiple sentences must have a full stop at
>> the end of each sentence.
>>
>> Signed-off-by: George Dunlap <george.dunlap@xxxxxxxxxx>
>> ---
>> CC: Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
>> CC: Ian Jackson <ian.jackson@xxxxxxxxxx>
>> CC: Jan Beulich <jbeulich@xxxxxxxx>
>> CC: Konrad Wilk <konrad.wilk@xxxxxxxxxx>
>> CC: Stefano Stabellini <sstabellini@xxxxxxxxxx>
>> CC: Tim Deegan <tim@xxxxxxx>
>> CC: Wei Liu <wei.liu2@xxxxxxxxxx>
>> ---
>>  CODING_STYLE | 4 +++-
>>  1 file changed, 3 insertions(+), 1 deletion(-)
>>
>> diff --git a/CODING_STYLE b/CODING_STYLE
>> index 95842e3..4c3b53a 100644
>> --- a/CODING_STYLE
>> +++ b/CODING_STYLE
>> @@ -93,7 +93,9 @@ Comments
>>  
>>  Only C style /* ... */ comments are to be used.  C++ style // comments
>>  should not be used.  Multi-word comments should begin with a capital
>> -letter and end with a full stop.
>> +letter.  Comments containing a single sentence may end with a full
>> +stop; comments containing several sentences must have a full stop
>> +after each sentence.
> 
> I would suggest a coding style that specifies the useful properties of a
> comment and not call out some irrelevant, minor grammar point.
> 
> So, I think this should be.
> 
> "Comments should be clear and understandable."

"I'm not happy with this idea but I would not argue against it." :-)

Or not very strenuously.  I think having spelling and grammar mistakes
does detract from my experience as a reader, and I think it makes the
code itself look bad to other people.  Lots of people are quite
judgemental about spelling and grammar and would have a worse opinion of
the quality of our code if the language quality in our comments were poor.

> Reviewers should be advised to not nit-pick grammar or spelling issues
> in comments unless they harm clarity or readability.
> 
> Committers who particularly care should be prepared to fix any minor
> grammar or spelling issues when committing.

For the most part I think submitters want to have proper grammar and
spelling; and I think if grammar and spelling mistakes in comments are
the only thing that needs changing most committers already offer to
change it when they check it in.

If there are other more substantial changes, then I don't think it's too
much to ask someone who's re-submitting a patch anyway to fix things up
while they're at it.

 -George


_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
https://lists.xen.org/xen-devel