Skip to contentSkip to conversation

CODING_STYLE: trivial update

PATCH Superseded Wei Yang 4 participants 15 messages Feb 19, 2019

v1 of 6 Superseded Latest is v6 →

lore
Share & tools
lore

Wei Yang

author
#0 lore raw

cover CODING_STYLE: trivial update

The first one is suggested by Igor Mammedov to provide rule for multiline code.

The second is a trivial fix to make example code all indented with 4 spaces.

Wei Yang (2):
CODING_STYLE: specify the indent rule for multiline code
CODING_STYLE: indent example code as all others

 CODING_STYLE | 34 ++++++++++++++++++++++++++++++----
 1 file changed, 30 insertions(+), 4 deletions(-)
Signature · 1 line
2.19.1
author
#1 lore raw

PATCH 1/2 CODING_STYLE: specify the indent rule for multiline code

We didn't specify the indent rule for multiline code here, which may misleading users. And in current code, the code use different rules.

Add this rule in CODING_STYLE to make sure this is clear to every one.

---
 CODING_STYLE | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)
CODING_STYLE +26 -0
index ec075dedc4..73f66ca185 100644
@@ -29,6 +29,32 @@ Spaces of course are superior to tabs because:
 
 Do not leave whitespace dangling off the ends of lines.
 
+1.1 Multiline Indent
+
+There are several places where indent is necessary:
+
+ - struct definition
+ - if/else
+ - while/for
+ - function definition & call
+
+All the above cases apply the same rule: indent with four spaces.
+
+While the last three case may face another situation: code should spread into
+several lines. In this case the rule is align the new line with first
+parentheses.
+
+For example:
+
+    if (a == 1 &&
+        b == 2)
+
+    while (a == 1 &&
+           b == 2)
+
+    do_something(arg1, arg2
+                 arg3)
+
 2. Line width
 
 Lines should be 80 characters; try not to make them longer.
Signature · 1 line
2.19.1
#2 lore raw

Re: [Qemu-devel] [PATCH 1/2] CODING_STYLE: specify the indent rule for multiline code

Hi,

Quoted 34 lines · Wei Yang

We didn't specify the indent rule for multiline code here, which may misleading users. And in current code, the code use different rules.

Add this rule in CODING_STYLE to make sure this is clear to every one.

---
 CODING_STYLE | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)
CODING_STYLE +15 -0
index ec075dedc4..73f66ca185 100644
@@ -29,6 +29,32 @@ Spaces of course are superior to tabs because:
 
 Do not leave whitespace dangling off the ends of lines.
 
+1.1 Multiline Indent
+
+There are several places where indent is necessary:
+
+ - struct definition
+ - if/else
+ - while/for
+ - function definition & call
+
+All the above cases apply the same rule: indent with four spaces.
+
+While the last three case may face another situation: code should spread into
+several lines. In this case the rule is align the new line with first
+parentheses.
+

CODING_STYLE Spaces of course are superior to tabs because: · line 56

Quoted 10 lines
CODING_STYLE +10 -0
+For example:
+
+    if (a == 1 &&
+        b == 2)
+
+    while (a == 1 &&
+           b == 2)
+
+    do_something(arg1, arg2
+                 arg3)

Thanks for clearing this.

What is still unclear is what to do when a function name is over 60 characters (you follow a library/API and can not shorten it), for example:

static void ccid_card_vscard_handle_message(PassthruState *card,

    const VSCMsgHeader *scr_msg_header);

What is the project guideline in this case?
(Cc'ed Peter).

Quoted 5 lines
CODING_STYLE +1 -0
+
 2. Line width
 
 Lines should be 80 characters; try not to make them longer.
#3 lore raw

Re: [Qemu-devel] [PATCH 1/2] CODING_STYLE: specify the indent rule for multiline code

Quoted 8 lines · Philippe Mathieu-Daudé

What is still unclear is what to do when a function name is over 60 characters (you follow a library/API and can not shorten it), for example:

static void ccid_card_vscard_handle_message(PassthruState *card,

    const VSCMsgHeader *scr_msg_header);

What is the project guideline in this case?

I don't know that we have an official guideline, but I've seen enough code doing that. I've also seen this style:

static void long_func_name(
parameter one, parameter two)

{
    if (condition) {
        call_some_really_long_name(
            arg1,
            arg2);
    }

where even the first argument is put at an indentation of 4 from the primary line.

Signature · 3 lines
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org
#4 lore raw

Re: [Qemu-devel] [PATCH 1/2] CODING_STYLE: specify the indent rule for multiline code

Quoted 23 lines · Eric Blake
Quoted 8 lines · Philippe Mathieu-Daudé

What is still unclear is what to do when a function name is over 60 characters (you follow a library/API and can not shorten it), for example:

static void ccid_card_vscard_handle_message(PassthruState *card,

    const VSCMsgHeader *scr_msg_header);

What is the project guideline in this case?

I don't know that we have an official guideline, but I've seen enough code doing that. I've also seen this style:

static void long_func_name(
parameter one, parameter two)

{
   if (condition) {
       call_some_really_long_name(
           arg1,
           arg2);
   }
Quoted 2 lines

where even the first argument is put at an indentation of 4 from the primary line.

We should put this style in the example too?

Quoted 5 lines
Signature · 4 lines
-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org
Signature · 2 lines
Wei Yang
Help you, Help me
#5 lore raw

Re: [Qemu-devel] [PATCH 1/2] CODING_STYLE: specify the indent rule for multiline code

In reply to Wei Yang
Quoted 19 lines · Wei Yang

We didn't specify the indent rule for multiline code here, which may misleading users. And in current code, the code use different rules.

Add this rule in CODING_STYLE to make sure this is clear to every one.

---
 CODING_STYLE | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)
CODING_STYLE +0 -0
index ec075dedc4..73f66ca185 100644
@@ -29,6 +29,32 @@ Spaces of course are superior to tabs because:
 
 Do not leave whitespace dangling off the ends of lines.
 

CODING_STYLE Spaces of course are superior to tabs because: · line 41

Quoted 10 lines
CODING_STYLE +10 -0
+1.1 Multiline Indent
+
+There are several places where indent is necessary:
+
+ - struct definition
+ - if/else
+ - while/for
+ - function definition & call
+
+All the above cases apply the same rule: indent with four spaces.

Is this redundant with the earlier statement that "QEMU indents are four spaces."?

CODING_STYLE Spaces of course are superior to tabs because: · line 45

Quoted 4 lines
CODING_STYLE +4 -0
+
+While the last three case may face another situation: code should spread into
+several lines. In this case the rule is align the new line with first
+parentheses.

Grammar is awkward - the leading 'while' makes it sound like that you have a dependent clause, but then never provide the independent clause. Maybe a completely different wording is better:

When breaking up a long line to fit within line widths, align the secondary lines just after the opening parenthesis of the first.

CODING_STYLE Spaces of course are superior to tabs because: · line 51

Quoted 6 lines
CODING_STYLE +6 -0
+
+For example:
+
+    if (a == 1 &&
+        b == 2)
+

Maybe:

if (a == 1 &&

    b == 2) {

to match our later recommendations on always using {}.

CODING_STYLE Spaces of course are superior to tabs because: · line 54

Quoted 3 lines
CODING_STYLE +3 -0
+    while (a == 1 &&
+           b == 2)
+

Similar.

CODING_STYLE Spaces of course are superior to tabs because: · line 57

Quoted 3 lines
CODING_STYLE +3 -0
+    do_something(arg1, arg2
+                 arg3)
+

and here, I'd include the ';' to make it a valid statement.

Quoted 4 lines
CODING_STYLE +0 -0
 2. Line width
 
 Lines should be 80 characters; try not to make them longer.
Signature · 3 lines
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org
#6 lore raw

Re: [Qemu-devel] [PATCH 1/2] CODING_STYLE: specify the indent rule for multiline code

Quoted 43 lines · Eric Blake
Quoted 19 lines · Wei Yang

We didn't specify the indent rule for multiline code here, which may misleading users. And in current code, the code use different rules.

Add this rule in CODING_STYLE to make sure this is clear to every one.

---
 CODING_STYLE | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)
CODING_STYLE +0 -0
index ec075dedc4..73f66ca185 100644
@@ -29,6 +29,32 @@ Spaces of course are superior to tabs because:
 
 Do not leave whitespace dangling off the ends of lines.
 

CODING_STYLE Spaces of course are superior to tabs because: · line 41

Quoted 10 lines
CODING_STYLE +10 -0
+1.1 Multiline Indent
+
+There are several places where indent is necessary:
+
+ - struct definition
+ - if/else
+ - while/for
+ - function definition & call
+
+All the above cases apply the same rule: indent with four spaces.

Is this redundant with the earlier statement that "QEMU indents are four spaces."?

CODING_STYLE Spaces of course are superior to tabs because: · line 45

Quoted 4 lines
CODING_STYLE +4 -0
+
+While the last three case may face another situation: code should spread into
+several lines. In this case the rule is align the new line with first
+parentheses.

Grammar is awkward - the leading 'while' makes it sound like that you have a dependent clause, but then never provide the independent clause. Maybe a completely different wording is better:

Quoted 3 lines

When breaking up a long line to fit within line widths, align the secondary lines just after the opening parenthesis of the first.

Sounds better.

Quoted 9 lines

CODING_STYLE Spaces of course are superior to tabs because: · line 51

Quoted 6 lines
CODING_STYLE +6 -0
+
+For example:
+
+    if (a == 1 &&
+        b == 2)
+

Maybe:

Quoted 5 lines

if (a == 1 &&
b == 2) {

to match our later recommendations on always using {}.

Yep.

Quoted 4 lines

CODING_STYLE Spaces of course are superior to tabs because: · line 54

Quoted 3 lines
CODING_STYLE +3 -0
+    while (a == 1 &&
+           b == 2)
+
Quoted 8 lines

Similar.

CODING_STYLE Spaces of course are superior to tabs because: · line 57

Quoted 3 lines
CODING_STYLE +3 -0
+    do_something(arg1, arg2
+                 arg3)
+

and here, I'd include the ';' to make it a valid statement.

Reasonable.

Quoted 9 lines
Quoted 4 lines
CODING_STYLE +0 -0
 2. Line width
 
 Lines should be 80 characters; try not to make them longer.
Signature · 3 lines
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org
Signature · 2 lines
Wei Yang
Help you, Help me
author
#7 lore raw

PATCH 2/2 CODING_STYLE: indent example code as all others

In reply to Wei Yang

All the example code are indented with four spaces except this one.

Fix this by adding four spaces here.

---
 CODING_STYLE | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
CODING_STYLE +4 -4
index 73f66ca185..27581d80c1 100644
@@ -134,10 +134,10 @@ block to a separate function altogether.
 When comparing a variable for (in)equality with a constant, list the
 constant on the right, as in:
 
-if (a == 1) {
-    /* Reads like: "If a equals 1" */
-    do_something();
-}
+    if (a == 1) {
+        /* Reads like: "If a equals 1" */
+        do_something();
+    }
 
 Rationale: Yoda conditions (as in 'if (1 == a)') are awkward to read.
 Besides, good compilers already warn users when '==' is mis-typed as '=',
Signature · 1 line
2.19.1
#8 lore raw

Re: [Qemu-devel] [PATCH 2/2] CODING_STYLE: indent example code as all others

Quoted 14 lines · Wei Yang

All the example code are indented with four spaces except this one.

Fix this by adding four spaces here.

---
 CODING_STYLE | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
CODING_STYLE +0 -0
index 73f66ca185..27581d80c1 100644

CODING_STYLE block to a separate function altogether. · line 138

Quoted 9 lines
CODING_STYLE +2 -4
@@ -134,10 +134,10 @@ block to a separate function altogether.
 When comparing a variable for (in)equality with a constant, list the
 constant on the right, as in:
 
-if (a == 1) {
-    /* Reads like: "If a equals 1" */
-    do_something();
-}
+    if (a == 1) {
+        /* Reads like: "If a equals 1" */

I guess you found a bug in the documentation :)

Since 8c06fbdf36bf4d the style asked is:

We now require Linux-kernel-style multiline comments:
/*
* line one
* line two
*/

Quoted 6 lines
CODING_STYLE +2 -0
+        do_something();
+    }
 
 Rationale: Yoda conditions (as in 'if (1 == a)') are awkward to read.
 Besides, good compilers already warn users when '==' is mis-typed as '=',
#9 lore raw

Re: [Qemu-devel] [PATCH 2/2] CODING_STYLE: indent example code as all others

Quoted 5 lines · Philippe Mathieu-Daudé

CODING_STYLE block to a separate function altogether. · line 138

Quoted 2 lines
CODING_STYLE +2 -0
+    if (a == 1) {
+        /* Reads like: "If a equals 1" */

I guess you found a bug in the documentation :)

Quoted 9 lines

Since 8c06fbdf36bf4d the style asked is:

We now require Linux-kernel-style multiline comments:
/*
* line one
* line two
*/

Quoted 1 line

+ do_something();

We only require winged multiline comments when the comment is actually multiline. In this case, the comment is a one-liner, and is just fine as written.

Signature · 3 lines
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org
#10 lore raw

Re: [Qemu-devel] [PATCH 2/2] CODING_STYLE: indent example code as all others

Quoted 15 lines · Eric Blake
Quoted 13 lines · Philippe Mathieu-Daudé

CODING_STYLE block to a separate function altogether. · line 138

Quoted 2 lines
CODING_STYLE +2 -0
+    if (a == 1) {
+        /* Reads like: "If a equals 1" */

I guess you found a bug in the documentation :)

Since 8c06fbdf36bf4d the style asked is:

We now require Linux-kernel-style multiline comments:
/*
* line one
* line two
*/

Quoted 5 lines
Quoted 1 line
Quoted 1 line

+ do_something();

We only require winged multiline comments when the comment is actually multiline. In this case, the comment is a one-liner, and is just fine as written.

Hmm I have a series where I moved code and changed from /* one line */ to the multi-line style, I wonder why and remember checkpatch errors. Maybe a side-effect from what b94e809d3e fixed.

Anyway, Wei do you mind adding a multi-line example here too?

With/without multi-line example:

Thanks!

Phil.

#11 lore raw

Re: [Qemu-devel] [PATCH 2/2] CODING_STYLE: indent example code as all others

Quoted 22 lines · Philippe Mathieu-Daudé
Quoted 15 lines · Eric Blake
Quoted 13 lines · Philippe Mathieu-Daudé

CODING_STYLE block to a separate function altogether. · line 138

Quoted 2 lines
CODING_STYLE +2 -0
+    if (a == 1) {
+        /* Reads like: "If a equals 1" */

I guess you found a bug in the documentation :)

Since 8c06fbdf36bf4d the style asked is:

We now require Linux-kernel-style multiline comments:
/*
* line one
* line two
*/

Quoted 5 lines
Quoted 1 line
Quoted 1 line

+ do_something();

We only require winged multiline comments when the comment is actually multiline. In this case, the comment is a one-liner, and is just fine as written.

Quoted 6 lines

Hmm I have a series where I moved code and changed from /* one line */ to the multi-line style, I wonder why and remember checkpatch errors. Maybe a side-effect from what b94e809d3e fixed.

Anyway, Wei do you mind adding a multi-line example here too?

A multi-line example for multiline comments?

This looks not relavant to this sectioin. I am afraid I will not add this example here. Sorry for that.

Quoted 6 lines

With/without multi-line example:

Thanks!

Phil.

Signature · 2 lines
Wei Yang
Help you, Help me
#12 lore raw

Re: [Qemu-devel] [PATCH 2/2] CODING_STYLE: indent example code as all others

Quoted 27 lines · Wei Yang
Quoted 26 lines · Philippe Mathieu-Daudé
Quoted 15 lines · Eric Blake
Quoted 13 lines · Philippe Mathieu-Daudé

CODING_STYLE block to a separate function altogether. · line 138

Quoted 2 lines
CODING_STYLE +2 -0
+    if (a == 1) {
+        /* Reads like: "If a equals 1" */

I guess you found a bug in the documentation :)

Since 8c06fbdf36bf4d the style asked is:

We now require Linux-kernel-style multiline comments:
/*
* line one
* line two
*/

Quoted 5 lines
Quoted 1 line
Quoted 1 line

+ do_something();

We only require winged multiline comments when the comment is actually multiline. In this case, the comment is a one-liner, and is just fine as written.

Hmm I have a series where I moved code and changed from /* one line */ to the multi-line style, I wonder why and remember checkpatch errors. Maybe a side-effect from what b94e809d3e fixed.

Quoted 7 lines
Quoted 2 lines

Anyway, Wei do you mind adding a multi-line example here too?

A multi-line example for multiline comments?

This looks not relavant to this sectioin. I am afraid I will not add this example here. Sorry for that.

No worries, R-b stands.

Quoted 7 lines
Quoted 6 lines

With/without multi-line example:

Thanks!

Phil.

#13 lore raw

Re: [Qemu-devel] [PATCH 2/2] CODING_STYLE: indent example code as all others

In reply to Philippe Mathieu-Daudé
Quoted 18 lines · Philippe Mathieu-Daudé
Quoted 17 lines · Wei Yang

All the example code are indented with four spaces except this one.

Fix this by adding four spaces here.

---
 CODING_STYLE | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
CODING_STYLE +0 -0
index 73f66ca185..27581d80c1 100644
@@ -134,10 +134,10 @@ block to a separate function altogether.
 When comparing a variable for (in)equality with a constant, list the
 constant on the right, as in:
 
Quoted 6 lines

CODING_STYLE block to a separate function altogether. · line 138

Quoted 6 lines
CODING_STYLE +2 -4
-if (a == 1) {
-    /* Reads like: "If a equals 1" */
-    do_something();
-}
+    if (a == 1) {
+        /* Reads like: "If a equals 1" */

I don't get your point.

You mean to put it into multiline comments?

Quoted 17 lines

I guess you found a bug in the documentation :)

Since 8c06fbdf36bf4d the style asked is:

We now require Linux-kernel-style multiline comments:
/*
* line one
* line two
*/

Quoted 6 lines
CODING_STYLE +2 -0
+        do_something();
+    }
 
 Rationale: Yoda conditions (as in 'if (1 == a)') are awkward to read.
 Besides, good compilers already warn users when '==' is mis-typed as '=',
Signature · 2 lines
Wei Yang
Help you, Help me
Reviewed-by on v1 2/2
#14 lore raw

Re: [Qemu-devel] [PATCH 2/2] CODING_STYLE: indent example code as all others

In reply to Wei Yang
Quoted 8 lines · Wei Yang

All the example code are indented with four spaces except this one.

Fix this by adding four spaces here.

---
 CODING_STYLE | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
Signature · 3 lines
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org