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

[Alex Williamson <alex.williamson@redhat.com>]

On Tue, 12 Jun 2018 20:12:02 +0200
Thomas Huth <thuth@redhat.com> wrote:

> On 12.06.2018 19:30, Richard Henderson wrote:
> > On 06/11/2018 04:17 AM, Peter Maydell wrote:  
> >> The codebase has a bit of a mix of different multiline
> >> comment styles. State a preference for the Linux kernel
> >> style:
> >>     /*
> >>      * Star on the left for each line.
> >>      * Leading slash-star and trailing star-slash
> >>      * each go on a line of their own.
> >>      */
> >>
> >> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> >> ---
> >> This is not my personal favourite, but seemed to be the
> >> closest we had to consensus in the mail thread for v1;
> >> I can live with it in order to avoid getting patches which
> >> use the styles I like even less :-)  
> > 
> > Honestly, I don't like this except for "important" comments.
> > 
> > A "small" comment, e.g. one that doesn't quite fit on a single line, now takes
> > 4 lines instead of 2.  Which is really annoying and IMO tends to break flow.
> > 
> > If you don't like
> > 
> >   /* gnu
> >      style */
> > 
> > or
> > 
> >   /* whatever
> >    * this is */
> > 
> > could you live with
> > 
> >   // c99/c++
> >   // comments  
> 
> FWIW:
> 
> +1 for one or two of those compact styles for two- or three-line comments.

or four-line or single paragraphs or comments that rhyme with
"orange"...  If the comment is too large for a single line, then take
some time to say it more concisely, or maybe it does deserve enough
thought to frame a nice paragraph for it.  We're well into personal
style here, so either this is important enough to make some people
unhappy or we should leave it to maintainer preference and consistency
within a file/area.  Thanks,

Alex