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

[George Dunlap <george.dunlap@xxxxxxxxxx>]

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