Re: [Qemu-devel] [PATCH] CODING_STYLE: Define our preferred form for multiline comments

[Thomas Huth]

On 05.06.2018 11:19, Peter Maydell wrote:
> On 5 June 2018 at 08:46, Cornelia Huck <address@hidden> wrote:
>> On Tue, 5 Jun 2018 06:33:22 +0200
>> Thomas Huth <address@hidden> wrote:
>>> On 05.06.2018 03:17, Alex Williamson wrote:
>>>> On Mon,  4 Jun 2018 17:21:40 +0100
>>>> Peter Maydell <address@hidden> wrote:
>>>>> +Multiline comments blocks should have a row of stars on the left
>>>>> +and the terminating */ on its own line:
>>>>> +    /* like
>>>>> +     * this
>>>>> +     */
>>>>> +Putting the initial /* on its own line is accepted, but not required.
>>>>
>>>> Could we say "at maintainer discretion", or is that always implied?  The
>>>> asymmetry of the proposed standard is not my favorite and a mostly
>>>> blank line before and after further supports standing out from
>>>> surrounding code.
>>> I also don't like the asymmetry. I'd prefer more dense comments, though:
>>>
>>>   /* like
>>>    * this */
> 
> Wow, I think that looks terrible :-)

... but ... but ... this color is so much better ... ? ;-)

>>> Anyway, could we either use that dense format or the kernel-style
>>> multi-lines-comment format, please? Mixing it asymmetrically is just ugly.
>>
>> I'd vote for the kernel style, then.
> 
> I don't particularly object to the kernel style (though it's not
> how I personally default to writing comments). I just didn't want
> to rule a huge chunk of our existing comments as out-of-standard
> for what I see as a relatively minor divergence in form --
> we do have a lot of no-leading-separate-/* comments. I can live
> with mandating kernel-style if it means we can rule out GNU-form
> and other weirdnesses though :-)

Ok, then maybe write that kernel-style is the preferred way, but also
mention that the "mixed" style is OK, too? If that helps to avoid that
somebody is sending hundreds of trivial patches to the list to correct
them, I'm fine with it.

 Thomas