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

[Thomas Huth <thuth@redhat.com>]

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.

 Thomas