docs/coding-style.rst | 76 +++++++++++++++++++++---------------------- 1 file changed, 38 insertions(+), 38 deletions(-)
In our coding style document we have examples of good and bad
code, which we mark as:
// Good
// Bad
respectively. But in the very same document we advocate for using
C style of comments over C++. Follow our own advice and switch
annotation to:
/* Good */
/* Bad */
And while at it, align these annotations within their blocks for
better readability.
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
---
docs/coding-style.rst | 76 +++++++++++++++++++++----------------------
1 file changed, 38 insertions(+), 38 deletions(-)
diff --git a/docs/coding-style.rst b/docs/coding-style.rst
index 92f6099d82..fe5fe9a906 100644
--- a/docs/coding-style.rst
+++ b/docs/coding-style.rst
@@ -161,24 +161,24 @@ a single space following them before the opening bracket. E.g.
::
- if(foo) // Bad
- if (foo) // Good
+ if(foo) /* Bad */
+ if (foo) /* Good */
Function implementations must **not** have any whitespace between
the function name and the opening bracket. E.g.
::
- int foo (int wizz) // Bad
- int foo(int wizz) // Good
+ int foo (int wizz) /* Bad */
+ int foo(int wizz) /* Good */
Function calls must **not** have any whitespace between the
function name and the opening bracket. E.g.
::
- bar = foo (wizz); // Bad
- bar = foo(wizz); // Good
+ bar = foo (wizz); /* Bad */
+ bar = foo(wizz); /* Good */
Function typedefs must **not** have any whitespace between the
closing bracket of the function name and opening bracket of the
@@ -186,16 +186,16 @@ arg list. E.g.
::
- typedef int (*foo) (int wizz); // Bad
- typedef int (*foo)(int wizz); // Good
+ typedef int (*foo) (int wizz); /* Bad */
+ typedef int (*foo)(int wizz); /* Good */
There must not be any whitespace immediately following any opening
bracket, or immediately prior to any closing bracket. E.g.
::
- int foo( int wizz ); // Bad
- int foo(int wizz); // Good
+ int foo( int wizz ); /* Bad */
+ int foo(int wizz); /* Good */
Commas
------
@@ -206,8 +206,8 @@ syntax-check'.
::
- call(a,b ,c);// Bad
- call(a, b, c); // Good
+ call(a,b ,c); /* Bad */
+ call(a, b, c); /* Good */
When declaring an enum or using a struct initializer that occupies
more than one line, use a trailing comma. That way, future edits
@@ -225,11 +225,11 @@ C99 allows trailing commas, remember that JSON and XDR do not.
enum {
VALUE_ONE,
- VALUE_TWO // Bad
+ VALUE_TWO /* Bad */
};
enum {
VALUE_THREE,
- VALUE_FOUR, // Good
+ VALUE_FOUR, /* Good */
};
Semicolons
@@ -243,10 +243,10 @@ not enforced, loop counters generally use post-increment.
::
- for (i = 0 ;i < limit ; ++i) { // Bad
- for (i = 0; i < limit; i++) { // Good
- for (;;) { // ok
- while (1) { // Better
+ for (i = 0 ;i < limit ; ++i) { /* Bad */
+ for (i = 0; i < limit; i++) { /* Good */
+ for (;;) { /* ok */
+ while (1) { /* Better */
Empty loop bodies are better represented with curly braces and a
comment, although use of a semicolon is not currently rejected.
@@ -254,9 +254,9 @@ comment, although use of a semicolon is not currently rejected.
::
while ((rc = waitpid(pid, &st, 0) == -1) &&
- errno == EINTR); // ok
+ errno == EINTR); /* ok */
while ((rc = waitpid(pid, &st, 0) == -1) &&
- errno == EINTR) { // Better
+ errno == EINTR) { /* Better */
/* nothing */
}
@@ -271,19 +271,19 @@ single-\ *statement* loop: each has only one *line* in its body.
::
- while (expr) // single line body; {} is optional
+ while (expr) /* single line body; {} is optional */
single_line_stmt();
::
while (expr(arg1,
- arg2)) // indentation makes it obvious it is single line,
- single_line_stmt(); // {} is optional (not enforced either way)
+ arg2)) /* indentation makes it obvious it is single line, */
+ single_line_stmt(); /* {} is optional (not enforced either way) */
::
while (expr1 &&
- expr2) { // multi-line, at same indentation, {} required
+ expr2) { /* multi-line, at same indentation, {} required */
single_line_stmt();
}
@@ -295,7 +295,7 @@ braces), thinking it is already a multi-statement loop:
::
- while (true) // BAD! multi-line body with no braces
+ while (true) /* BAD! multi-line body with no braces */
/* comment... */
single_line_stmt();
@@ -303,7 +303,7 @@ Do this instead:
::
- while (true) { // Always put braces around a multi-line body.
+ while (true) { /* Always put braces around a multi-line body. */
/* comment... */
single_line_stmt();
}
@@ -325,8 +325,8 @@ To reiterate, don't do this:
::
- if (expr) // BAD: no braces around...
- while (expr_2) { // ... a multi-line body
+ if (expr) /* BAD: no braces around... */
+ while (expr_2) { /* ... a multi-line body */
...
}
@@ -356,11 +356,11 @@ longer, multi-line block be the ``else`` block.
...
}
else
- x = y; // BAD: braceless "else" with braced "then",
- // and short block last
+ x = y; /* BAD: braceless "else" with braced "then",
+ * and short block last */
if (expr)
- x = y; // BAD: braceless "if" with braced "else"
+ x = y; /* BAD: braceless "if" with braced "else" */
else {
...
...
@@ -375,7 +375,7 @@ rather than after the more involved block:
::
if (!expr) {
- x = y; // putting the smaller block first is more readable
+ x = y; /* putting the smaller block first is more readable */
} else {
...
...
@@ -403,19 +403,19 @@ itself.
void
foo(int a, int b)
- { // correct - function body
+ { /* correct - function body */
int 2d[][] = {
- { // correct - complex initialization
+ { /* correct - complex initialization */
1, 2,
},
};
if (a)
- { // BAD: compound brace on its own line
+ { /* BAD: compound brace on its own line */
do_stuff();
}
- { // correct - nested scope
+ { /* correct - nested scope */
int tmp;
- if (a < b) { // correct - hanging brace
+ if (a < b) { /* correct - hanging brace */
tmp = b;
b = a;
a = tmp;
@@ -601,7 +601,7 @@ calling another function.
x = y + 20;
- char *z = NULL; // <===
+ char *z = NULL; /* <=== */
...
}
--
2.39.2On Tue, Apr 04, 2023 at 12:02:10 +0200, Michal Privoznik wrote: > In our coding style document we have examples of good and bad > code, which we mark as: > > // Good > // Bad > > respectively. But in the very same document we advocate for using > C style of comments over C++. Follow our own advice and switch > annotation to: > > /* Good */ > /* Bad */ > > And while at it, align these annotations within their blocks for > better readability. > > Signed-off-by: Michal Privoznik <mprivozn@redhat.com> > --- > docs/coding-style.rst | 76 +++++++++++++++++++++---------------------- > 1 file changed, 38 insertions(+), 38 deletions(-) Reviewed-by: Peter Krempa <pkrempa@redhat.com>
© 2016 - 2024 Red Hat, Inc.