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

[David Vrabel <david.vrabel@xxxxxxxxxx>]

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

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@xxxxxxxxxxxxx
https://lists.xen.org/xen-devel