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

[Markus Armbruster <armbru@redhat.com>]

Peter Maydell <peter.maydell@linaro.org> writes:

> On 5 June 2018 at 08:46, Cornelia Huck <cohuck@redhat.com> wrote:
>> On Tue, 5 Jun 2018 06:33:22 +0200
>> Thomas Huth <thuth@redhat.com> wrote:
>>> On 05.06.2018 03:17, Alex Williamson wrote:
>>> > On Mon,  4 Jun 2018 17:21:40 +0100
>>> > Peter Maydell <peter.maydell@linaro.org> wrote:
>>> >> +Multiline comments blocks should have a row of stars on the left
>>> >> +and the terminating */ on its own line:
>>> >> +    /* like
>>> >> +     * this
>>> >> +     */

Uh, winging just one end of the comment offends my eyes.

>>> >> +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 :-)

Even more terrible, you wanted to say ;)

>>> 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 :-)

Let's mandate kernel-style for new code.  I could live with giving
maintainers license to tolerate certain other styles.  The fewer, the
better, though.