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

[John Snow]

On 06/13/2018 08:30 AM, Peter Maydell wrote:
> On 12 June 2018 at 18:30, Richard Henderson
> <address@hidden> 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 <address@hidden>
>>> ---
>>> 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.
> 
> That's why I prefer
>  /* two
>   * lines
>   */
> style over kernel-style. But apparently nobody else does...

The same reasoning could be used to justify

/* two
 * lines */

as it's ... actually just two lines. I think people don't seem to like
this much either (why? does it look 'naked' on the end?) and seemingly
the asymmetry is a bit of a killer for the isolated close-comment style:

/* asymmetric
 * three lines
 */

so we seemed to have arrived on the vertically symmetric:

/*
 * four
 * lines
 */

style. I think this is a pretty reasonable compromise with the tastes of
the various maintainers that have chimed in so far -- it seems to be
nobody's favorite but everyone's second choice :)

If there is concern this will balloon "almost" single line comments into
four lines, I think the overall strategy of being either more concise
(or being 70 characters more detailed!) is probably reasonable enough.

...Overall I think it probably doesn't matter too much as long as
comments in each individual file are consistent.

It would only begin to matter terribly much if we actually decided we
wanted to do a doxygen-style doc generation for our internal APIs for
compatibility with, say, fancier IDEs than vim/emacs.

As it stands, we're pretty inconsistent about which exact style we apply
when we "document" internal functions -- sometimes we document the
header, sometimes the implementation, sometimes both (but differently!)
and always with different styles all over the place. That's the real
problem, IMO.

For non-javadoc style comments that aren't intended to document a
function in some methodical way, I think as long as it looks nice in the
file as deemed by the maintainer and it's consistent, it's probably fine.

> 
> thanks
> -- PMM
>
Now I can say after working at Red Hat for four years that I've finally
had a real life "tabs vs spaces" argument, too. I guess I had a good run
without :)

--js