CODING_STYLE: Mention preferred comment form

Message ID 1486144722-6021-1-git-send-email-peter.maydell@linaro.org
State Superseded
Headers show

Commit Message

Peter Maydell Feb. 3, 2017, 5:58 p.m.
Our defacto coding style strongly prefers /* */ style comments
over the single-line // style, and checkpatch enforces this,
but we don't actually document this. Mention it in CODING_STYLE.

Suggested-by: Thomas Huth <thuth@redhat.com>
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

---
 CODING_STYLE | 7 +++++++
 1 file changed, 7 insertions(+)

-- 
2.7.4

Comments

Markus Armbruster Feb. 4, 2017, 10 a.m. | #1
Peter Maydell <peter.maydell@linaro.org> writes:

> Our defacto coding style strongly prefers /* */ style comments

> over the single-line // style, and checkpatch enforces this,

> but we don't actually document this. Mention it in CODING_STYLE.

>

> Suggested-by: Thomas Huth <thuth@redhat.com>

> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

> ---

>  CODING_STYLE | 7 +++++++

>  1 file changed, 7 insertions(+)

>

> diff --git a/CODING_STYLE b/CODING_STYLE

> index f53180b..2fa0c0b 100644

> --- a/CODING_STYLE

> +++ b/CODING_STYLE

> @@ -116,3 +116,10 @@ if (a == 1) {

>  Rationale: Yoda conditions (as in 'if (1 == a)') are awkward to read.

>  Besides, good compilers already warn users when '==' is mis-typed as '=',

>  even when the constant is on the right.

> +

> +7. Comment style

> +

> +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.


Reviewed-by: Markus Armbruster <armbru@redhat.com>
Fam Zheng Feb. 4, 2017, 2:48 p.m. | #2
On Fri, 02/03 17:58, Peter Maydell wrote:
> Our defacto coding style strongly prefers /* */ style comments

> over the single-line // style, and checkpatch enforces this,

> but we don't actually document this. Mention it in CODING_STYLE.

> 

> Suggested-by: Thomas Huth <thuth@redhat.com>

> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

> ---

>  CODING_STYLE | 7 +++++++

>  1 file changed, 7 insertions(+)

> 

> diff --git a/CODING_STYLE b/CODING_STYLE

> index f53180b..2fa0c0b 100644

> --- a/CODING_STYLE

> +++ b/CODING_STYLE

> @@ -116,3 +116,10 @@ if (a == 1) {

>  Rationale: Yoda conditions (as in 'if (1 == a)') are awkward to read.

>  Besides, good compilers already warn users when '==' is mis-typed as '=',

>  even when the constant is on the right.

> +

> +7. Comment style

> +

> +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.


Reviewed-by: Fam Zheng <famz@redhat.com>
Laurent Vivier Feb. 5, 2017, 6:02 p.m. | #3
Le 03/02/2017 à 18:58, Peter Maydell a écrit :
> Our defacto coding style strongly prefers /* */ style comments

> over the single-line // style, and checkpatch enforces this,

> but we don't actually document this. Mention it in CODING_STYLE.

> 

> Suggested-by: Thomas Huth <thuth@redhat.com>

> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

> ---

>  CODING_STYLE | 7 +++++++

>  1 file changed, 7 insertions(+)

> 

> diff --git a/CODING_STYLE b/CODING_STYLE

> index f53180b..2fa0c0b 100644

> --- a/CODING_STYLE

> +++ b/CODING_STYLE

> @@ -116,3 +116,10 @@ if (a == 1) {

>  Rationale: Yoda conditions (as in 'if (1 == a)') are awkward to read.

>  Besides, good compilers already warn users when '==' is mis-typed as '=',

>  even when the constant is on the right.

> +

> +7. Comment style

> +

> +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.

> 


Reviewed-by: Laurent Vivier <laurent@vivier.eu>
Stefan Hajnoczi Feb. 13, 2017, 2 p.m. | #4
On Fri, Feb 03, 2017 at 05:58:42PM +0000, Peter Maydell wrote:
> Our defacto coding style strongly prefers /* */ style comments

> over the single-line // style, and checkpatch enforces this,

> but we don't actually document this. Mention it in CODING_STYLE.

> 

> Suggested-by: Thomas Huth <thuth@redhat.com>

> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

> ---

>  CODING_STYLE | 7 +++++++

>  1 file changed, 7 insertions(+)


Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
Michael Tokarev Feb. 15, 2017, 10:17 a.m. | #5
03.02.2017 20:58, Peter Maydell wrote:
> Our defacto coding style strongly prefers /* */ style comments

> over the single-line // style, and checkpatch enforces this,

> but we don't actually document this. Mention it in CODING_STYLE.


Applied to -trivial, thanks!

/mjt

Patch hide | download patch | download mbox

diff --git a/CODING_STYLE b/CODING_STYLE
index f53180b..2fa0c0b 100644
--- a/CODING_STYLE
+++ b/CODING_STYLE
@@ -116,3 +116,10 @@  if (a == 1) {
 Rationale: Yoda conditions (as in 'if (1 == a)') are awkward to read.
 Besides, good compilers already warn users when '==' is mis-typed as '=',
 even when the constant is on the right.
+
+7. Comment style
+
+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.