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

[Cornelia Huck <cohuck@redhat.com>]

On Tue, 12 Jun 2018 12:47:29 -0600
Alex Williamson <alex.williamson@redhat.com> wrote:

> 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,

+1 to maintainer judgment and consistency.

(And FWIW, c++ style comments are what I use when I comment something
out for debugging, so I don't like them in regular code :)