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

[John Snow <jsnow@redhat.com>]

On 06/04/2018 12:21 PM, Peter Maydell 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.
> +(Some of the existing comments in the codebase use the GNU Coding
> +Standards form which does not have stars on the left; avoid this
> +when writing new comments.)
> +
> +Rationale: Consistency, and ease of visually picking out a multiline
> +comment from the surrounding code.
> +
>  8. trace-events style
>  
>  8.1 0x prefix
> 

Is there some name for the unholy abomination that is the combination of
both styles?:

/* Like this, but without the trailing
 * end-comment on a standalone line. */

I prefer the asterisks on the left because it makes it obvious when
grepping that it's from a comment block; I dislike the standalone
comment for taking up a bunch of room for seemingly no reason.

...Not that I expect to change your mind, or to suggest I've got enough
paint for a shed this large, so any standard is better than no standard...

--js