On 09/08/2018 19:03, Peter Maydell wrote:
> On 9 August 2018 at 17:43, Paolo Bonzini <[email protected]> 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>"
Yes, there is overlap between QEMU and Linux developers, but really only
in a few subsystems (s390, pSeries, networking---which uses the "other"
comment style), and I don't see why we should pretend that QEMU and
Linux use similar coding styles. In fact they couldn't be more
different: spaces vs. tabs, indent-4 vs. indent-8, camelcase struct
names with typedefs... Basically the only thing that is the same is
lowercase for variable names and braces on the same line as the
statement. Linux's checkpatch was a useful base not because Linux and
QEMU are similar, but only because of the complex expression parsing
stuff that really is the same for _any_ sane coding style (even GNU ;)).
Paolo
