| Message ID | 1470303456-13210-1-git-send-email-george.dunlap@citrix.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
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
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
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
>>> 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
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
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>
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
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
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
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 '*'.
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(-)