From 2948f0cde3974185ad22d6721438cf85df852877 Mon Sep 17 00:00:00 2001 From: Peter Maydell Date: Fri, 15 Jun 2018 14:57:14 +0100 Subject: [PATCH] CODING_STYLE: Define our preferred form for multiline comments 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 Reviewed-by: Eric Blake Reviewed-by: Cornelia Huck Reviewed-by: Markus Armbruster Reviewed-by: Alex Williamson Reviewed-by: Thomas Huth Reviewed-by: John Snow Reviewed-by: Stefan Hajnoczi Message-id: 20180611141716.3813-1-peter.maydell@linaro.org --- CODING_STYLE | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/CODING_STYLE b/CODING_STYLE index 12ba58ee29..ec075dedc4 100644 --- a/CODING_STYLE +++ b/CODING_STYLE @@ -124,6 +124,23 @@ 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 comment blocks should have a row of stars on the left, +and the initial /* and terminating */ both on their own lines: + /* + * like + * this + */ +This is the same format required by the Linux kernel coding style. + +(Some of the existing comments in the codebase use the GNU Coding +Standards form which does not have stars on the left, or other +variations; avoid these when writing new comments, but don't worry +about converting to the preferred form unless you're editing that +comment anyway.) + +Rationale: Consistency, and ease of visually picking out a multiline +comment from the surrounding code. + 8. trace-events style 8.1 0x prefix