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

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

[George Dunlap]

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@citrix.com>
---
CC: Andrew Cooper <andrew.cooper3@citrix.com>
CC: Ian Jackson <ian.jackson@citrix.com>
CC: Jan Beulich <jbeulich@suse.com>
CC: Konrad Wilk <konrad.wilk@oracle.com>
CC: Stefano Stabellini <sstabellini@kernel.org>
CC: Tim Deegan <tim@xen.org>
CC: Wei Liu <wei.liu2@citrix.com>
---
 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.
 
 Multi-line comment blocks should start and end with comment markers on
 separate lines and each line should begin with a leading '*'.
-- 
2.1.4


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

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

[George Dunlap]

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@citrix.com>

Quoting myself from another thread:

---
I think the issue here as that to me, these kinds of comments are not
"plain written text"; they're more like signs or labels.  If you search
Google Images for "sign" or "clothing label", you'll find that no
single-sentence signs have full stops at the end.

That's why to me it actually feels like having a full stop at the end of
a comment like this is actively wrong -- it changes it from one type of
speech into another type of speech.  I wouldn't bike-shed over the issue
by insisting a full stop be removed; but it would definitely irritate me
to be told that I had to add one.
---

 -George


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

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

[George Dunlap]

On 04/08/16 10:46, George Dunlap 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@citrix.com>
> 
> Quoting myself from another thread:
> 
> ---
> I think the issue here as that to me, these kinds of comments are not
> "plain written text"; they're more like signs or labels.  If you search
> Google Images for "sign" or "clothing label", you'll find that no
> single-sentence signs have full stops at the end.

Or perhaps to be more accurate -- these comments are like labels on a
flow chart, designed to be high-level actions to help the reader figure
out what's going on.  If you Google flow chards you'll also find that
none of the flow chart labels include full stops.

 -George


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

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

[David Vrabel]

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@citrix.com>
> ---
> CC: Andrew Cooper <andrew.cooper3@citrix.com>
> CC: Ian Jackson <ian.jackson@citrix.com>
> CC: Jan Beulich <jbeulich@suse.com>
> CC: Konrad Wilk <konrad.wilk@oracle.com>
> CC: Stefano Stabellini <sstabellini@kernel.org>
> CC: Tim Deegan <tim@xen.org>
> CC: Wei Liu <wei.liu2@citrix.com>
> ---
>  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."

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.

David

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

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

[Jan Beulich]

>>> On 04.08.16 at 11:37, <george.dunlap@citrix.com> wrote:
> --- 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.

If we no longer demand a full stop, why would we demand an upper
case letter at the start?

Jan


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

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

[George Dunlap]

On 04/08/16 11:09, Jan Beulich wrote:
>>>> On 04.08.16 at 11:37, <george.dunlap@citrix.com> wrote:
>> --- 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.
> 
> If we no longer demand a full stop, why would we demand an upper
> case letter at the start?

Because that "looks right" to me; and indeed, if you look at images of
flow charts, you'll find that they all start with a capital letter.

 -George


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

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

[Ian Jackson]

George Dunlap writes ("[PATCH] CODING_STYLE: Allow single-sentence comments without full stops"):
> 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@citrix.com>

Seriously ?

Yes, the bike shed can be purple with occasional mauve.

Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>

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

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

[George Dunlap]

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@citrix.com>
>> ---
>> CC: Andrew Cooper <andrew.cooper3@citrix.com>
>> CC: Ian Jackson <ian.jackson@citrix.com>
>> CC: Jan Beulich <jbeulich@suse.com>
>> CC: Konrad Wilk <konrad.wilk@oracle.com>
>> CC: Stefano Stabellini <sstabellini@kernel.org>
>> CC: Tim Deegan <tim@xen.org>
>> CC: Wei Liu <wei.liu2@citrix.com>
>> ---
>>  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@lists.xen.org
https://lists.xen.org/xen-devel

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

[George Dunlap]

On Thu, Aug 4, 2016 at 11:25 AM, Ian Jackson <ian.jackson@eu.citrix.com> wrote:
> George Dunlap writes ("[PATCH] CODING_STYLE: Allow single-sentence comments without full stops"):
>> 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@citrix.com>
>
> Seriously ?
>
> Yes, the bike shed can be purple with occasional mauve.
>
> Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>

Thanks Ian.

The other comments so far don't seem to be objections to this
relaxation, but about whether standards should be relaxed further.  If
I don't hear any objections by Monday I'll check this patch in and let
others submit follow-on patches if they want.

 -George

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

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

[George Dunlap]

On Fri, Aug 5, 2016 at 2:56 PM, George Dunlap <george.dunlap@citrix.com> wrote:
> On Thu, Aug 4, 2016 at 11:25 AM, Ian Jackson <ian.jackson@eu.citrix.com> wrote:
>> George Dunlap writes ("[PATCH] CODING_STYLE: Allow single-sentence comments without full stops"):
>>> 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@citrix.com>
>>
>> Seriously ?
>>
>> Yes, the bike shed can be purple with occasional mauve.
>>
>> Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
>
> Thanks Ian.
>
> The other comments so far don't seem to be objections to this
> relaxation, but about whether standards should be relaxed further.  If
> I don't hear any objections by Monday I'll check this patch in and let
> others submit follow-on patches if they want.

And pushed.

 -George

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