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

[Cornelia Huck <cohuck@redhat.com>]

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:
> >   
> >> The codebase has a bit of a mix of
> >>  /* multiline comments
> >>   * like this
> >>   */
> >> and
> >>  /* multiline comments like this
> >>     in the GNU Coding Standards style */
> >>
> >> State a preference for the former.
> >>
> >> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> >> ---
> >> I admit that to some extent I'm imposing my aesthetic
> >> preferences here; pretty sure we have a lot more style
> >> 1 comments than style 2, though.
> >> ---
> >>  CODING_STYLE | 13 +++++++++++++
> >>  1 file changed, 13 insertions(+)
> >>
> >> diff --git a/CODING_STYLE b/CODING_STYLE
> >> index 12ba58ee293..fb1d1f1cd62 100644
> >> --- a/CODING_STYLE
> >> +++ b/CODING_STYLE
> >> @@ -124,6 +124,19 @@ We use traditional C-style /* */ comments and avoid // comments.
> >>  Rationale: The // form is valid in C99, so this is purely a matter of
> >>  consistency of style. The checkpatch script will warn you about this.
> >>  
> >> +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 */
> 
> 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'd also like the bikeshed to be painted in a grayed blue-green.