Re: [Qemu-devel] [PATCH] scripts/checkpatch.pl: Enforce multiline comment syntax

[Markus Armbruster]

Paolo Bonzini <address@hidden> writes:

> On 09/08/2018 19:03, Peter Maydell wrote:
>> On 9 August 2018 at 17:43, Paolo Bonzini <address@hidden> wrote:
>>>> I'm still not used to the leeading-/*-on-it's-own style,
>>>> so having checkpatch catch my lapses is handy...
>>>
>>> ... if it's not what we are using, why enforce it?
>> 
>> See the enormous long threads on the recent changes to CODING_STYLE:
>> https://lists.gnu.org/archive/html/qemu-devel/2018-06/msg00696.html
>> https://lists.gnu.org/archive/html/qemu-devel/2018-06/msg02717.html
>> 
>> Basically, I wanted to rule out things like
>> 
>>   /* this
>>      weirdness */
>> 
>> and lots of other people wanted (a) to not have
>> 
>>   /* this thing
>>    * which I think is fine
>>    */
>> 
>> and (b) to consistently define only one format as OK.
>> 
>> So I accepted having my personal preferred format not being
>> permitted in order to get consensus on getting rid of the
>> formats I think are really ugly :-)
>
> This is one of the cases where we are decently consistent:
>
> Lone "/*" or "/**": 9986 cases
>       of which in the first column: 7617
>       of which the first line in the file (license headers): 2834
>       regex: ^[ \t]*/\*\*?[ \t]*$
>
> "/*" with the first line of the comment: 11246
>       of which in the first column: 4985
>       of which the first line in the file: 97
>       regex: ^[ \t]*/\*\*?+(?:(?!\*/).)+?$
>
> License headers almost always have the "lone /*" format.  Apart from
> license headers, 63% of the comments have the now-deprecated format.
>
> Inside functions, 73% of the comments have the now-deprecated format.
> Outside functions it's 50-50.  That's because there are 2024 doc
> comments, which in turn are 50% of the comments that are 1) outside the
> functions 2) using a lone "/*".
>
> So my proposal, which is actually consistent with what QEMU is doing, is
> the following:
>
> 1) the first line of a file should always be "/*", otherwise warn
>
> 2) a comment that starts with "/**" should have it on a lone line
>
> 3) every other multiline comment should start with
> "/*<whitespace><something>"

(3) is not consistent with what QEMU is doing in this case, since
according to your data there is no consistency in what QEMU is doing.

Moreover, requiring winged comment start in some, but not all places is
more complicated than simply requiring it everywhere.

The "enourmous long threads" quoted by Peter resulted in strong
agreement we don't want

   /* this
      weirdness */

and rough consensus to go with

   /*
    * Wing your multiline comment
    * at both ends, please.
    */

going forward.

If there's actually no consensus on this, then the issue devolves to
subsystem maintainers.

For what it's worth, I've been demanding "wing your multi-line comments
at both ends", and intend to continue doing so, unless we adopt a
different project-wide multi-line comment style, enforced by checkpatch.

[...]