[PATCH 1/9] CodingStyle: make Documentation/CodingStyle into symlink

[PATCH 1/9] CodingStyle: make Documentation/CodingStyle into symlink

[Alexey Dobriyan]

Every time I open Documentation/CodingStyle it says the party moved
somewhere else. :-(

Of course, I forget where it moved to by the next time.

Signed-off-by: Alexey Dobriyan <adobriyan@gmail.com>
---
 Documentation/CodingStyle | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
 mode change 100644 => 120000 Documentation/CodingStyle

diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle
deleted file mode 100644
index 320983ca114e..000000000000
--- a/Documentation/CodingStyle
+++ /dev/null
@@ -1 +0,0 @@
-This file has moved to process/coding-style.rst
diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle
new file mode 120000
index 000000000000..b4a9864269eb
--- /dev/null
+++ b/Documentation/CodingStyle
@@ -0,0 +1 @@
+process/coding-style.rst
\ No newline at end of file
-- 
2.49.0

[PATCH 2/9] CodingStyle: delete explicit numbering

[Alexey Dobriyan]

All _real_ documentation systems have a way to number
chapters/sections/subsections automatically.

I haven't found a way to do it in this reST thingy so keep them
unnumbered for the time being.

Signed-off-by: Alexey Dobriyan <adobriyan@gmail.com>
---
 Documentation/process/coding-style.rst | 100 ++++++++++++-------------
 1 file changed, 50 insertions(+), 50 deletions(-)

diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index 19d2ed47ff79..a4fbe45c3eb9 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -15,8 +15,8 @@ and NOT read it.  Burn them, it's a great symbolic gesture.
 Anyway, here goes:
 
 
-1) Indentation
---------------
+Indentation
+-----------
 
 Tabs are 8 characters, and thus indentations are also 8 characters.
 There are heretic movements that try to make indentations 4 (or even 2!)
@@ -95,8 +95,8 @@ used for indentation, and the above example is deliberately broken.
 Get a decent editor and don't leave whitespace at the end of lines.
 
 
-2) Breaking long lines and strings
-----------------------------------
+Breaking long lines and strings
+-------------------------------
 
 Coding style is all about readability and maintainability using commonly
 available tools.
@@ -117,8 +117,8 @@ However, never break user-visible strings such as printk messages because
 that breaks the ability to grep for them.
 
 
-3) Placing Braces and Spaces
-----------------------------
+Placing Braces and Spaces
+-------------------------
 
 The other issue that always comes up in C styling is the placement of
 braces.  Unlike the indent size, there are few technical reasons to
@@ -231,8 +231,8 @@ Also, use braces when a loop contains more than a single simple statement:
 			do_something();
 	}
 
-3.1) Spaces
-***********
+Spaces
+******
 
 Linux kernel style for use of spaces depends (mostly) on
 function-versus-keyword usage.  Use a space after (most) keywords.  The
@@ -303,8 +303,8 @@ of patches, this may make later patches in the series fail by changing their
 context lines.
 
 
-4) Naming
----------
+Naming
+------
 
 C is a Spartan language, and your naming conventions should follow suit.
 Unlike Modula-2 and Pascal programmers, C programmers do not use cute
@@ -356,8 +356,8 @@ specification that mandates those terms. For new specifications
 translate specification usage of the terminology to the kernel coding
 standard where possible.
 
-5) Typedefs
------------
+Typedefs
+--------
 
 Please don't use things like ``vps_t``.
 It's a **mistake** to use typedef for structures and pointers. When you see a
@@ -440,8 +440,8 @@ In general, a pointer, or a struct that has elements that can reasonably
 be directly accessed should **never** be a typedef.
 
 
-6) Functions
-------------
+Functions
+---------
 
 Functions should be short and sweet, and do just one thing.  They should
 fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24,
@@ -480,8 +480,8 @@ closing function brace line.  E.g.:
 	}
 	EXPORT_SYMBOL(system_is_up);
 
-6.1) Function prototypes
-************************
+Function prototypes
+*******************
 
 In function prototypes, include parameter names with their data types.
 Although this is not required by the C language, it is preferred in Linux
@@ -523,8 +523,8 @@ below, compared to the **declaration** example above)::
 	...
  }
 
-7) Centralized exiting of functions
------------------------------------
+Centralized exiting of functions
+--------------------------------
 
 Albeit deprecated by some people, the equivalent of the goto statement is
 used frequently by compilers in form of the unconditional jump instruction.
@@ -595,8 +595,8 @@ fix for this is to split it up into two error labels ``err_free_bar:`` and
 Ideally you should simulate errors to test all exit paths.
 
 
-8) Commenting
--------------
+Commenting
+----------
 
 Comments are good, but there is also a danger of over-commenting.  NEVER
 try to explain HOW your code works in a comment: it's much better to
@@ -635,8 +635,8 @@ multiple data declarations).  This leaves you room for a small comment on each
 item, explaining its use.
 
 
-9) You've made a mess of it
----------------------------
+You've made a mess of it
+------------------------
 
 That's OK, we all do.  You've probably been told by your long-time Unix
 user helper that ``GNU emacs`` automatically formats the C sources for
@@ -728,8 +728,8 @@ set automatically if you are using an editor that is compatible with
 EditorConfig. See the official EditorConfig website for more information:
 https://editorconfig.org/
 
-10) Kconfig configuration files
--------------------------------
+Kconfig configuration files
+---------------------------
 
 For all of the Kconfig* configuration files throughout the source tree,
 the indentation is somewhat different.  Lines under a ``config`` definition
@@ -757,8 +757,8 @@ For full documentation on the configuration files, see the file
 Documentation/kbuild/kconfig-language.rst.
 
 
-11) Data structures
--------------------
+Data structures
+---------------
 
 Data structures that have visibility outside the single-threaded
 environment they are created and destroyed in should always have
@@ -789,8 +789,8 @@ Remember: if another thread can find your data structure, and you don't
 have a reference count on it, you almost certainly have a bug.
 
 
-12) Macros, Enums and RTL
--------------------------
+Macros, Enums and RTL
+---------------------
 
 Names of macros defining constants and labels in enums are capitalized.
 
@@ -893,8 +893,8 @@ The cpp manual deals with macros exhaustively. The gcc internals manual also
 covers RTL which is used frequently with assembly language in the kernel.
 
 
-13) Printing kernel messages
-----------------------------
+Printing kernel messages
+------------------------
 
 Kernel developers like to be seen as literate. Do mind the spelling
 of kernel messages to make a good impression. Do not use incorrect
@@ -929,8 +929,8 @@ already inside a debug-related #ifdef section, printk(KERN_DEBUG ...) can be
 used.
 
 
-14) Allocating memory
----------------------
+Allocating memory
+-----------------
 
 The kernel provides the following general purpose memory allocators:
 kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and
@@ -971,8 +971,8 @@ These generic allocation functions all emit a stack dump on failure when used
 without __GFP_NOWARN so there is no use in emitting an additional failure
 message when NULL is returned.
 
-15) The inline disease
-----------------------
+The inline disease
+------------------
 
 There appears to be a common misperception that gcc has a magic "make me
 faster" speedup option called ``inline``. While the use of inlines can be
@@ -999,8 +999,8 @@ appears outweighs the potential value of the hint that tells gcc to do
 something it would have done anyway.
 
 
-16) Function return values and names
-------------------------------------
+Function return values and names
+--------------------------------
 
 Functions can return values of many different kinds, and one of the
 most common is a value indicating whether the function succeeded or
@@ -1034,8 +1034,8 @@ result.  Typical examples would be functions that return pointers; they use
 NULL or the ERR_PTR mechanism to report failure.
 
 
-17) Using bool
---------------
+Using bool
+----------
 
 The Linux kernel bool type is an alias for the C99 _Bool type. bool values can
 only evaluate to 0 or 1, and implicit or explicit conversion to bool
@@ -1064,8 +1064,8 @@ readable alternative if the call-sites have naked true/false constants.
 Otherwise limited use of bool in structures and arguments can improve
 readability.
 
-18) Don't re-invent the kernel macros
--------------------------------------
+Don't re-invent the kernel macros
+---------------------------------
 
 The header file include/linux/kernel.h contains a number of macros that
 you should use, rather than explicitly coding some variant of them yourself.
@@ -1087,8 +1087,8 @@ need them.  Feel free to peruse that header file to see what else is already
 defined that you shouldn't reproduce in your code.
 
 
-19) Editor modelines and other cruft
-------------------------------------
+Editor modelines and other cruft
+--------------------------------
 
 Some editors can interpret configuration information embedded in source files,
 indicated with special markers.  For example, emacs interprets lines marked
@@ -1121,8 +1121,8 @@ own custom mode, or may have some other magic method for making indentation
 work correctly.
 
 
-20) Inline assembly
--------------------
+Inline assembly
+---------------
 
 In architecture-specific code, you may need to use inline assembly to interface
 with CPU or platform functionality.  Don't hesitate to do so when necessary.
@@ -1153,8 +1153,8 @@ the next instruction in the assembly output:
 	     : /* outputs */ : /* inputs */ : /* clobbers */);
 
 
-21) Conditional Compilation
----------------------------
+Conditional Compilation
+-----------------------
 
 Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c
 files; doing so makes code harder to read and logic harder to follow.  Instead,
@@ -1202,8 +1202,8 @@ expression used.  For instance:
 	#endif /* CONFIG_SOMETHING */
 
 
-22) Do not crash the kernel
----------------------------
+Do not crash the kernel
+-----------------------
 
 In general, the decision to crash the kernel belongs to the user, rather
 than to the kernel developer.
@@ -1264,8 +1264,8 @@ Use BUILD_BUG_ON() for compile-time assertions
 The use of BUILD_BUG_ON() is acceptable and encouraged, because it is a
 compile-time assertion that has no effect at runtime.
 
-Appendix I) References
-----------------------
+References
+----------
 
 The C Programming Language, Second Edition
 by Brian W. Kernighan and Dennis M. Ritchie.
-- 
2.49.0

[PATCH 3/9] CodingStyle: advise on using "sysctl" in sysctl variables

[Alexey Dobriyan]

Signed-off-by: Alexey Dobriyan <adobriyan@gmail.com>
---
 Documentation/process/coding-style.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index a4fbe45c3eb9..ac9c1dbe00b7 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -356,6 +356,10 @@ specification that mandates those terms. For new specifications
 translate specification usage of the terminology to the kernel coding
 standard where possible.
 
+Variables holding data exported via sysctl interface better have ``sysctl``
+somewhere in the name. This should remind developer that its value may change
+at any moment unsynchronized with the rest of the code.
+
 Typedefs
 --------
 
-- 
2.49.0

[PATCH 4/9] CodingStyle: mention "typedef struct S {} S;" if typedef is used

[Alexey Dobriyan]

Signed-off-by: Alexey Dobriyan <adobriyan@gmail.com>
---
 Documentation/process/coding-style.rst | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index ac9c1dbe00b7..5c5902a0f897 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -443,6 +443,20 @@ EVER use a typedef unless you can clearly match one of those rules.
 In general, a pointer, or a struct that has elements that can reasonably
 be directly accessed should **never** be a typedef.
 
+If you must use ``typedef`` consider using identical names for both the type
+and its alias so that the type can be forward declared if necessary:
+
+.. code-block:: c
+
+	typedef struct S { ... } S;
+	typedef union U { ... } U;
+
+	struct S;
+	union U;
+	int f(struct S *s, union U *u);
+
+
+Forward declaring by typedef'ed name doesn't work.
 
 Functions
 ---------
-- 
2.49.0

[PATCH 5/9] CodingStyle: institute better inline assembly formatting

[Alexey Dobriyan]

Signed-off-by: Alexey Dobriyan <adobriyan@gmail.com>
---
 Documentation/process/coding-style.rst | 40 +++++++++++++++++++++-----
 1 file changed, 33 insertions(+), 7 deletions(-)

diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index 5c5902a0f897..63c41125e713 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -1159,16 +1159,42 @@ You may need to mark your asm statement as volatile, to prevent GCC from
 removing it if GCC doesn't notice any side effects.  You don't always need to
 do so, though, and doing so unnecessarily can limit optimization.
 
-When writing a single inline assembly statement containing multiple
-instructions, put each instruction on a separate line in a separate quoted
-string, and end each string except the last with ``\n\t`` to properly indent
-the next instruction in the assembly output:
+Inline assembly statements are formatted as follows:
 
 .. code-block:: c
 
-	asm ("magic %reg1, #42\n\t"
-	     "more_magic %reg2, %reg3"
-	     : /* outputs */ : /* inputs */ : /* clobbers */);
+	asm [volatile] (
+		"insn1 r0, r1, r2\n\t"
+		"insn2 r0, 1\n\t"
+		: /* possibly empty output list */
+		: /* possibly empty input list */
+		: /* possibly empty clobber list */
+		[: goto label list]
+	);
+
+All keywords are placed on a single line.
+There is a space between ``asm``/``volatile`` and ``(`` so it looks nicer.
+
+Each assembly instruction is placed on a separate line as does
+output/input/clobber/label lists even if they are empty. This is done to
+a) prevent unnecessary reformatting if ``volatile`` is added/removed and
+b) to visually separate outputs from inputs from clobbers, so it's easier
+to understand what's going on.
+
+Each line of inline assembly statement except the first and the last is
+indented by 1 tab relative to the initial ``asm`` keyword.
+
+Each assembly instruction is ended by ``"\n\t"``. It looks ugly and distracting
+in the source code but keeps formatting of ``-S`` output consistent.
+
+Very short and simple inline assembly statements are permitted to be one-liners:
+
+.. code-block:: c
+
+	asm ("movdqa %%xmm0, %0" : "=m" (*buf));
+
+Those are usually 1:1 wrappers around single CPU instruction.
+``"\n\t"`` suffix is unnecessary in this case as the compiler will insert it anyway.
 
 
 Conditional Compilation
-- 
2.49.0

[PATCH 6/9] CodingStyle: recommend static_assert/_Static_assert

[Alexey Dobriyan]

Linux's BUG_ON is done backwards (condition is inverted).
But it is a long story.

However C11/C23 allow to partially transition to what all normal
programmers are used to, namely assert().

Deprecate BUILD_BUG_ON, recommend static_assert/_Static_assert.
And then some day BUG_ON will be flipped as well.

Signed-off-by: Alexey Dobriyan <adobriyan@gmail.com>
---
 Documentation/process/coding-style.rst | 23 +++++++++++++++++++----
 1 file changed, 19 insertions(+), 4 deletions(-)

diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index 63c41125e713..f8d5151eb0d2 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -1302,11 +1302,26 @@ asked the kernel to crash if a WARN*() fires, and such users must be
 prepared to deal with the consequences of a system that is somewhat more
 likely to crash.
 
-Use BUILD_BUG_ON() for compile-time assertions
-**********************************************
+Use ``_Static_assert``/``static_assert`` to test things at compile time
+***********************************************************************
 
-The use of BUILD_BUG_ON() is acceptable and encouraged, because it is a
-compile-time assertion that has no effect at runtime.
+C99 has standardized ``_Static_assert`` keyword and C23 added ``static_assert``
+later making Linux specific ``BUILD_BUG_ON`` macro obsolete.
+
+Note that both forms of static assertions are classified as declaration and
+thus can be used (almost) anywhere in the code including top-level.
+Don't introduce fake functions to test things at compile time:
+
+.. code-block:: c
+
+	_Static_assert(sizeof(u32) == 4);
+	static_assert(sizeof(struct S) == 8);
+
+Also note that the second argument to ``static_assert`` can be omitted as an
+extension. Sometimes filename and line number of a compile error is all you
+need.
+
+See https://en.cppreference.com/w/c/language/_Static_assert for more information.
 
 References
 ----------
-- 
2.49.0

[PATCH 7/9] CodingStyle: new variable declaration placement rule

[Alexey Dobriyan]

Linux finally compiles without -Wdeclaration-after-statement allowing
to declare variables anywhere in the code.

The rule is that variable is declared as late as possible:

1) it is possible to typo a variable and use by mistake between
   declaration and first legitimate use.

   Declaring variable later decreases this risk.

2) it is possible to typo variable between last legitimate use and
   the end of the scope.

   Declaring variable in the innermost scope decreases this risk.

3) declaring ALAP (as late as possible) often allows to merge declaration
   and assignment into declaration with initializer. This saves LOC
   without readability loss.

4) declaring ALAP allows to use "const" on the variable if necessary.

   Linux doesn't use "const" much outside of "const T*" but with
   split declaration/assignment it is not possible at all.

4) declaring lower naturally breaks some misguided rules (I'm being
   polite here) about declarations: there is a rule saying that
   declaration block in the beginning of the scope must be sorted
   by length forming trapezoid-like shape

   	XXXXXXXXXXXXXXXXXXXXX
	XXXXXXXXXXXXXXXXXXX
	XXXXXXXXXXX
	XXXXXXXXX
	int rv;

   so the code looks nicer (allegedly). This is misguided (still polite)
   because code is formatted not for of objectively good characteristics
   (bug risk, codegen quality, easy of maintainance) but for subjective
   qualities like being aesthetically pleasing to look at.

5) K&R rule about declaring variables in the beginning of the scope is
   pointless restriction. It is very obvious after programming something
   other than C. All popular programming languages either never had K&R
   rule or discarded it at some point implying that even if it was
   useful (it wasn't), it was so marginally useful that everyone thought
   it is not worth it.

This patch makes 100% of the code non-compliant, but, oh well...

Signed-off-by: Alexey Dobriyan <adobriyan@gmail.com>
---
 Documentation/process/coding-style.rst | 72 ++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)

diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index f8d5151eb0d2..e17de69845ff 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -95,6 +95,78 @@ used for indentation, and the above example is deliberately broken.
 Get a decent editor and don't leave whitespace at the end of lines.
 
 
+Variable declarations
+---------------------
+
+Each variable is declared in the innermost scope possible
+where ``for`` initialization clause counts as a scope as well.
+
+Inside specific scope each variable is declared as late as possible as if
+declarations have "mass" and "fall down":
+
+.. code-block:: c
+
+	int f(void *priv)
+	{
+		struct xxx_obj *obj = to_xxx_obj(priv);
+
+		rcu_read_lock();
+		int s_xxx = 0;
+		for (int i = 0; i < n_xxx; i++) {
+			s_xxx += obj->xxx[i];
+		}
+		rcu_read_unlock();
+
+		unsigned long flags;
+		spin_lock_irqsave(&obj->lock, &flags);
+		int rv = obj_make(obj, s_xxx);
+		spin_unlock_irqrestore(&obj->lock, &flags);
+		return rv;
+	}
+
+
+These rules minimise a) the risk of variable misuse between declaration and
+first legitimate use, b) allow to transform declaration and first assignment
+into declaration with initializer saving LOC on average without readability
+loss and c) allow to use ``const`` if necessary:
+
+.. code-block:: c
+
+	T a;
+	T b;
+
+	a = g();/* bug, should be "b = " */
+
+	a = f();
+
+		vs
+
+	T b;
+	a = g(); /* compile error */
+	[const] T a = f(); /* OK */
+
+Each declaration is put on its own line:
+
+.. code-block:: c
+
+	T a = ...;
+	T tmp;
+
+C allows to declare multiple variables in the same statement but it is
+a misfeature. It leads to confusion if pointers are involved, even more
+confusion and long lines with initializers (likely going above character
+limit) and avoidable changes in patches.
+
+Very long declarations are split after the ``=`` character:
+
+.. code-block:: c
+
+	struct xxx_obj *obj =
+		xxx_obj_alloc(Long, list, of, arguments);
+
+Most of the time both lines fit just fine into the character limit afterwards.
+
+
 Breaking long lines and strings
 -------------------------------
 
-- 
2.49.0

[PATCH 8/9] CodingStyle: tell people how to split long "for" loops

[Alexey Dobriyan]

Signed-off-by: Alexey Dobriyan <adobriyan@gmail.com>
---
 Documentation/process/coding-style.rst | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index e17de69845ff..494ab3201112 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -183,7 +183,21 @@ Descendants are always substantially shorter than the parent and
 are placed substantially to the right.  A very commonly used style
 is to align descendants to a function open parenthesis.
 
-These same rules are applied to function headers with a long argument list.
+These same rules are applied to function prototypes with a long argument list.
+
+Very long ``for`` loops are split at the ``;`` characters making it easier
+to see which code goes to which clause:
+
+.. code-block:: c
+
+	for (int i = 0;
+	     i < N;
+	     i += 1)
+	{
+	}
+
+Opening curly is placed on a separate line then to make it easier to tell
+loop body from iteration clause.
 
 However, never break user-visible strings such as printk messages because
 that breaks the ability to grep for them.
-- 
2.49.0

[PATCH 9/9] CodingStyle: flip the rule about curlies

[Alexey Dobriyan]

Require set of curlies {} in all if/else branches and all loops
not matter how simple.

The rationale is that maintaining curlies increases churn and make
patches bigger when those if/else branches grow and shrink so it is
easier to always add them.

There are more important things in life than herding curlies.

Signed-off-by: Alexey Dobriyan <adobriyan@gmail.com>
---
 Documentation/process/coding-style.rst | 57 +++++++++++++++-----------
 1 file changed, 32 insertions(+), 25 deletions(-)

diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index 494ab3201112..dc18ff40ebf2 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -280,43 +280,50 @@ supply of new-lines on your screen is not a renewable resource (think
 25-line terminal screens here), you have more empty lines to put
 comments on.
 
-Do not unnecessarily use braces where a single statement will do.
+All ``if``, ``for``, ``do``-``while``, ``switch`` and ``while`` statements
+use braces even when C grammar allows to omit them:
 
 .. code-block:: c
 
-	if (condition)
-		action();
-
-and
-
-.. code-block:: c
-
-	if (condition)
-		do_this();
-	else
-		do_that();
-
-This does not apply if only one branch of a conditional statement is a single
-statement; in the latter case use braces in both branches:
+	if (cond) {
+		t();
+	}
 
-.. code-block:: c
+	if (cond) {
+		t();
+	} else {
+		f();
+	}
 
-	if (condition) {
-		do_this();
-		do_that();
+	if (cond1) {
+		t1();
+	} else if (cond2) {
+		t2();
 	} else {
-		otherwise();
+		f();
 	}
 
-Also, use braces when a loop contains more than a single simple statement:
+	for (int i = 0; i < N; i += 1) {
+		f(i);
+	}
 
-.. code-block:: c
+	do {
+		g();
+	} while (0);
 
-	while (condition) {
-		if (test)
-			do_something();
+	switch (x) {
+	case X1:
+		f();
 	}
 
+	while (1) {
+		f();
+	}
+
+In the future, code will be added and deleted but braces stay untouched.
+Maitaining them when if branches, loop bodies grow and shrink is useless
+busywork not even worthy of discussion.
+
 Spaces
 ******
 
-- 
2.49.0

Re: [PATCH 1/9] CodingStyle: make Documentation/CodingStyle into symlink

[Ozgur Kara]

Alexey Dobriyan <adobriyan@gmail.com>, 9 May 2025 Cum, 23:35 tarihinde
şunu yazdı:
>
> Every time I open Documentation/CodingStyle it says the party moved
> somewhere else. :-(
>

Hello,

I dont understand, this already exists so when you look in
Documentation/CodingStyle file it will guide you?

$ cat Documentation/CodingStyle
This file has moved to process/coding-style.rst

$ cat Documentation/process/coding-style.rst

This was processed for .rst file.

Regards

Ozgur

> Of course, I forget where it moved to by the next time.
>
> Signed-off-by: Alexey Dobriyan <adobriyan@gmail.com>
> ---
>  Documentation/CodingStyle | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>  mode change 100644 => 120000 Documentation/CodingStyle
>
> diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle
> deleted file mode 100644
> index 320983ca114e..000000000000
> --- a/Documentation/CodingStyle
> +++ /dev/null
> @@ -1 +0,0 @@
> -This file has moved to process/coding-style.rst
> diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle
> new file mode 120000
> index 000000000000..b4a9864269eb
> --- /dev/null
> +++ b/Documentation/CodingStyle
> @@ -0,0 +1 @@
> +process/coding-style.rst
> \ No newline at end of file
> --
> 2.49.0
>
>
>
>

Re: [PATCH 9/9] CodingStyle: flip the rule about curlies

[Randy Dunlap]

On 5/9/25 1:34 PM, Alexey Dobriyan wrote:
> Require set of curlies {} in all if/else branches and all loops
> not matter how simple.
> 
> The rationale is that maintaining curlies increases churn and make
> patches bigger when those if/else branches grow and shrink so it is
> easier to always add them.
> 
> There are more important things in life than herding curlies.
> 
> Signed-off-by: Alexey Dobriyan <adobriyan@gmail.com>
> ---
>  Documentation/process/coding-style.rst | 57 +++++++++++++++-----------
>  1 file changed, 32 insertions(+), 25 deletions(-)
> 
> diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
> index 494ab3201112..dc18ff40ebf2 100644
> --- a/Documentation/process/coding-style.rst
> +++ b/Documentation/process/coding-style.rst
> @@ -280,43 +280,50 @@ supply of new-lines on your screen is not a renewable resource (think
>  25-line terminal screens here), you have more empty lines to put
>  comments on.
>  
> -Do not unnecessarily use braces where a single statement will do.
> +All ``if``, ``for``, ``do``-``while``, ``switch`` and ``while`` statements
> +use braces even when C grammar allows to omit them:
>  
>  .. code-block:: c
>  
> -	if (condition)
> -		action();
> -
> -and
> -
> -.. code-block:: c
> -
> -	if (condition)
> -		do_this();
> -	else
> -		do_that();
> -
> -This does not apply if only one branch of a conditional statement is a single
> -statement; in the latter case use braces in both branches:
> +	if (cond) {
> +		t();
> +	}
>  
> -.. code-block:: c
> +	if (cond) {
> +		t();
> +	} else {
> +		f();
> +	}
>  
> -	if (condition) {
> -		do_this();
> -		do_that();
> +	if (cond1) {
> +		t1();
> +	} else if (cond2) {
> +		t2();
>  	} else {
> -		otherwise();
> +		f();
>  	}
>  
> -Also, use braces when a loop contains more than a single simple statement:
> +	for (int i = 0; i < N; i += 1) {
> +		f(i);
> +	}
>  
> -.. code-block:: c
> +	do {
> +		g();
> +	} while (0);
>  
> -	while (condition) {
> -		if (test)
> -			do_something();
> +	switch (x) {
> +	case X1:
> +		f();
>  	}
>  
> +	while (1) {
> +		f();
> +	}
> +
> +In the future, code will be added and deleted but braces stay untouched.
> +Maitaining them when if branches, loop bodies grow and shrink is useless

   Maintaining

> +busywork not even worthy of discussion.
> +
>  Spaces
>  ******
>  

-- 
~Randy

Re: [PATCH 9/9] CodingStyle: flip the rule about curlies

[Greg KH]

On Fri, May 09, 2025 at 11:34:30PM +0300, Alexey Dobriyan wrote:
> Require set of curlies {} in all if/else branches and all loops
> not matter how simple.

Sorry, but no, we are not going to change this long-term coding style
rule for no real reason at this point in time.

greg k-h

Re: [PATCH 4/9] CodingStyle: mention "typedef struct S {} S;" if typedef is used

[Greg KH]

On Fri, May 09, 2025 at 11:34:25PM +0300, Alexey Dobriyan wrote:
> Signed-off-by: Alexey Dobriyan <adobriyan@gmail.com>
> ---
>  Documentation/process/coding-style.rst | 14 ++++++++++++++
>  1 file changed, 14 insertions(+)

We can't take patches without any changelog text, sorry.

Re: [PATCH 6/9] CodingStyle: recommend static_assert/_Static_assert

[Greg KH]

On Fri, May 09, 2025 at 11:34:27PM +0300, Alexey Dobriyan wrote:
> Linux's BUG_ON is done backwards (condition is inverted).
> But it is a long story.
> 
> However C11/C23 allow to partially transition to what all normal
> programmers are used to, namely assert().
> 
> Deprecate BUILD_BUG_ON, recommend static_assert/_Static_assert.
> And then some day BUG_ON will be flipped as well.

Odd, why are you attempting to make all of these mandates without
actually changing the code itself first?  That's just asking for major
churn for no good reason...

Sorry, but this series makes no sense to me.

greg k-h

Re: [PATCH 1/9] CodingStyle: make Documentation/CodingStyle into symlink

[Jonathan Corbet]

Alexey Dobriyan <adobriyan@gmail.com> writes:

> Every time I open Documentation/CodingStyle it says the party moved
> somewhere else. :-(
>
> Of course, I forget where it moved to by the next time.
>
> Signed-off-by: Alexey Dobriyan <adobriyan@gmail.com>
> ---

No 0/9 cover letter?

Just FYI, I won't apply coding-style patches without a strong sense that
there is a consensus behind them...I suspect that could prove to be a
high bar here.

Thanks,

jon

Re: [PATCH 4/9] CodingStyle: mention "typedef struct S {} S;" if typedef is used

[Mauro Carvalho Chehab]

Em Fri,  9 May 2025 23:34:25 +0300
Alexey Dobriyan <adobriyan@gmail.com> escreveu:

> Signed-off-by: Alexey Dobriyan <adobriyan@gmail.com>
> ---
>  Documentation/process/coding-style.rst | 14 ++++++++++++++
>  1 file changed, 14 insertions(+)
> 
> diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
> index ac9c1dbe00b7..5c5902a0f897 100644
> --- a/Documentation/process/coding-style.rst
> +++ b/Documentation/process/coding-style.rst
> @@ -443,6 +443,20 @@ EVER use a typedef unless you can clearly match one of those rules.
>  In general, a pointer, or a struct that has elements that can reasonably
>  be directly accessed should **never** be a typedef.
>  
> +If you must use ``typedef`` consider using identical names for both the type
> +and its alias so that the type can be forward declared if necessary:

Better not, as symbols with duplicated names will generate a Sphinx warning (*). 

(*) It shouldn't, but there is a pending issue on Sphinx since version 3.1
    still not addressed:

	https://github.com/sphinx-doc/sphinx/pull/8313

Regards,

Thanks,
Mauro

Re: [PATCH 4/9] CodingStyle: mention "typedef struct S {} S;" if typedef is used

[Mauro Carvalho Chehab]

Em Fri,  9 May 2025 23:34:25 +0300
Alexey Dobriyan <adobriyan@gmail.com> escreveu:

> Signed-off-by: Alexey Dobriyan <adobriyan@gmail.com>
> ---
>  Documentation/process/coding-style.rst | 14 ++++++++++++++
>  1 file changed, 14 insertions(+)
> 
> diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
> index ac9c1dbe00b7..5c5902a0f897 100644
> --- a/Documentation/process/coding-style.rst
> +++ b/Documentation/process/coding-style.rst
> @@ -443,6 +443,20 @@ EVER use a typedef unless you can clearly match one of those rules.
>  In general, a pointer, or a struct that has elements that can reasonably
>  be directly accessed should **never** be a typedef.
>  
> +If you must use ``typedef`` consider using identical names for both the type
> +and its alias so that the type can be forward declared if necessary:

Better not, as symbols with duplicated names will generate a Sphinx
warning(*), depending on how they're documented and used.

(*) It shouldn't, but there is a pending issue on Sphinx since version 3.1
    still not addressed:

	https://github.com/sphinx-doc/sphinx/pull/8313

Regards,

Thanks,
Mauro

Re: [PATCH 8/9] CodingStyle: tell people how to split long "for" loops

[David Laight]

On Fri,  9 May 2025 23:34:29 +0300
Alexey Dobriyan <adobriyan@gmail.com> wrote:

> Signed-off-by: Alexey Dobriyan <adobriyan@gmail.com>
> ---
>  Documentation/process/coding-style.rst | 16 +++++++++++++++-
>  1 file changed, 15 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
> index e17de69845ff..494ab3201112 100644
> --- a/Documentation/process/coding-style.rst
> +++ b/Documentation/process/coding-style.rst
> @@ -183,7 +183,21 @@ Descendants are always substantially shorter than the parent and
>  are placed substantially to the right.  A very commonly used style
>  is to align descendants to a function open parenthesis.
>  
> -These same rules are applied to function headers with a long argument list.
> +These same rules are applied to function prototypes with a long argument list.
> +
> +Very long ``for`` loops are split at the ``;`` characters making it easier
> +to see which code goes to which clause:
> +
> +.. code-block:: c
> +
> +	for (int i = 0;
> +	     i < N;
> +	     i += 1)
> +	{
> +	}
> +
> +Opening curly is placed on a separate line then to make it easier to tell
> +loop body from iteration clause.

Is that actually the style - I don't remember seeing it.

The location of the { isn't a significant problem with for (;;), it can be
much worse elsewhere.
In reality the 'align with the (' is what causes the problems, either
double indenting (two tabs) or half indent (4 spaces - to annoy anyone who
sets an editor to 4 space tabs) is more readable.

For for (;;) loops I'll normally try moving the initialisation outside the
loop and even put an inverted condition inside the loop to avoid long lines.

If a #define all bets are off :-)

	David



>  
>  However, never break user-visible strings such as printk messages because
>  that breaks the ability to grep for them.

Re: [PATCH 2/9] CodingStyle: delete explicit numbering

[Jani Nikula]

On Fri, 09 May 2025, Alexey Dobriyan <adobriyan@gmail.com> wrote:
> All _real_ documentation systems have a way to number
> chapters/sections/subsections automatically.
>
> I haven't found a way to do it in this reST thingy so keep them
> unnumbered for the time being.

I suppose you didn't look very hard. ;)

You can do it using the sectnum directive [1], but personally I'd prefer
just dropping them altogether.

And if you're changing the headings anyway, perhaps switch to the more
uniform heading adornments as described in
Documentation/doc-guide/sphinx.rst.

BR,
Jani.


[1] https://docutils.sourceforge.io/docs/ref/rst/directives.html#automatic-section-numbering


>
> Signed-off-by: Alexey Dobriyan <adobriyan@gmail.com>
> ---
>  Documentation/process/coding-style.rst | 100 ++++++++++++-------------
>  1 file changed, 50 insertions(+), 50 deletions(-)
>
> diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
> index 19d2ed47ff79..a4fbe45c3eb9 100644
> --- a/Documentation/process/coding-style.rst
> +++ b/Documentation/process/coding-style.rst
> @@ -15,8 +15,8 @@ and NOT read it.  Burn them, it's a great symbolic gesture.
>  Anyway, here goes:
>  
>  
> -1) Indentation
> ---------------
> +Indentation
> +-----------
>  
>  Tabs are 8 characters, and thus indentations are also 8 characters.
>  There are heretic movements that try to make indentations 4 (or even 2!)
> @@ -95,8 +95,8 @@ used for indentation, and the above example is deliberately broken.
>  Get a decent editor and don't leave whitespace at the end of lines.
>  
>  
> -2) Breaking long lines and strings
> -----------------------------------
> +Breaking long lines and strings
> +-------------------------------
>  
>  Coding style is all about readability and maintainability using commonly
>  available tools.
> @@ -117,8 +117,8 @@ However, never break user-visible strings such as printk messages because
>  that breaks the ability to grep for them.
>  
>  
> -3) Placing Braces and Spaces
> -----------------------------
> +Placing Braces and Spaces
> +-------------------------
>  
>  The other issue that always comes up in C styling is the placement of
>  braces.  Unlike the indent size, there are few technical reasons to
> @@ -231,8 +231,8 @@ Also, use braces when a loop contains more than a single simple statement:
>  			do_something();
>  	}
>  
> -3.1) Spaces
> -***********
> +Spaces
> +******
>  
>  Linux kernel style for use of spaces depends (mostly) on
>  function-versus-keyword usage.  Use a space after (most) keywords.  The
> @@ -303,8 +303,8 @@ of patches, this may make later patches in the series fail by changing their
>  context lines.
>  
>  
> -4) Naming
> ----------
> +Naming
> +------
>  
>  C is a Spartan language, and your naming conventions should follow suit.
>  Unlike Modula-2 and Pascal programmers, C programmers do not use cute
> @@ -356,8 +356,8 @@ specification that mandates those terms. For new specifications
>  translate specification usage of the terminology to the kernel coding
>  standard where possible.
>  
> -5) Typedefs
> ------------
> +Typedefs
> +--------
>  
>  Please don't use things like ``vps_t``.
>  It's a **mistake** to use typedef for structures and pointers. When you see a
> @@ -440,8 +440,8 @@ In general, a pointer, or a struct that has elements that can reasonably
>  be directly accessed should **never** be a typedef.
>  
>  
> -6) Functions
> -------------
> +Functions
> +---------
>  
>  Functions should be short and sweet, and do just one thing.  They should
>  fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24,
> @@ -480,8 +480,8 @@ closing function brace line.  E.g.:
>  	}
>  	EXPORT_SYMBOL(system_is_up);
>  
> -6.1) Function prototypes
> -************************
> +Function prototypes
> +*******************
>  
>  In function prototypes, include parameter names with their data types.
>  Although this is not required by the C language, it is preferred in Linux
> @@ -523,8 +523,8 @@ below, compared to the **declaration** example above)::
>  	...
>   }
>  
> -7) Centralized exiting of functions
> ------------------------------------
> +Centralized exiting of functions
> +--------------------------------
>  
>  Albeit deprecated by some people, the equivalent of the goto statement is
>  used frequently by compilers in form of the unconditional jump instruction.
> @@ -595,8 +595,8 @@ fix for this is to split it up into two error labels ``err_free_bar:`` and
>  Ideally you should simulate errors to test all exit paths.
>  
>  
> -8) Commenting
> --------------
> +Commenting
> +----------
>  
>  Comments are good, but there is also a danger of over-commenting.  NEVER
>  try to explain HOW your code works in a comment: it's much better to
> @@ -635,8 +635,8 @@ multiple data declarations).  This leaves you room for a small comment on each
>  item, explaining its use.
>  
>  
> -9) You've made a mess of it
> ----------------------------
> +You've made a mess of it
> +------------------------
>  
>  That's OK, we all do.  You've probably been told by your long-time Unix
>  user helper that ``GNU emacs`` automatically formats the C sources for
> @@ -728,8 +728,8 @@ set automatically if you are using an editor that is compatible with
>  EditorConfig. See the official EditorConfig website for more information:
>  https://editorconfig.org/
>  
> -10) Kconfig configuration files
> --------------------------------
> +Kconfig configuration files
> +---------------------------
>  
>  For all of the Kconfig* configuration files throughout the source tree,
>  the indentation is somewhat different.  Lines under a ``config`` definition
> @@ -757,8 +757,8 @@ For full documentation on the configuration files, see the file
>  Documentation/kbuild/kconfig-language.rst.
>  
>  
> -11) Data structures
> --------------------
> +Data structures
> +---------------
>  
>  Data structures that have visibility outside the single-threaded
>  environment they are created and destroyed in should always have
> @@ -789,8 +789,8 @@ Remember: if another thread can find your data structure, and you don't
>  have a reference count on it, you almost certainly have a bug.
>  
>  
> -12) Macros, Enums and RTL
> --------------------------
> +Macros, Enums and RTL
> +---------------------
>  
>  Names of macros defining constants and labels in enums are capitalized.
>  
> @@ -893,8 +893,8 @@ The cpp manual deals with macros exhaustively. The gcc internals manual also
>  covers RTL which is used frequently with assembly language in the kernel.
>  
>  
> -13) Printing kernel messages
> -----------------------------
> +Printing kernel messages
> +------------------------
>  
>  Kernel developers like to be seen as literate. Do mind the spelling
>  of kernel messages to make a good impression. Do not use incorrect
> @@ -929,8 +929,8 @@ already inside a debug-related #ifdef section, printk(KERN_DEBUG ...) can be
>  used.
>  
>  
> -14) Allocating memory
> ----------------------
> +Allocating memory
> +-----------------
>  
>  The kernel provides the following general purpose memory allocators:
>  kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and
> @@ -971,8 +971,8 @@ These generic allocation functions all emit a stack dump on failure when used
>  without __GFP_NOWARN so there is no use in emitting an additional failure
>  message when NULL is returned.
>  
> -15) The inline disease
> -----------------------
> +The inline disease
> +------------------
>  
>  There appears to be a common misperception that gcc has a magic "make me
>  faster" speedup option called ``inline``. While the use of inlines can be
> @@ -999,8 +999,8 @@ appears outweighs the potential value of the hint that tells gcc to do
>  something it would have done anyway.
>  
>  
> -16) Function return values and names
> -------------------------------------
> +Function return values and names
> +--------------------------------
>  
>  Functions can return values of many different kinds, and one of the
>  most common is a value indicating whether the function succeeded or
> @@ -1034,8 +1034,8 @@ result.  Typical examples would be functions that return pointers; they use
>  NULL or the ERR_PTR mechanism to report failure.
>  
>  
> -17) Using bool
> ---------------
> +Using bool
> +----------
>  
>  The Linux kernel bool type is an alias for the C99 _Bool type. bool values can
>  only evaluate to 0 or 1, and implicit or explicit conversion to bool
> @@ -1064,8 +1064,8 @@ readable alternative if the call-sites have naked true/false constants.
>  Otherwise limited use of bool in structures and arguments can improve
>  readability.
>  
> -18) Don't re-invent the kernel macros
> --------------------------------------
> +Don't re-invent the kernel macros
> +---------------------------------
>  
>  The header file include/linux/kernel.h contains a number of macros that
>  you should use, rather than explicitly coding some variant of them yourself.
> @@ -1087,8 +1087,8 @@ need them.  Feel free to peruse that header file to see what else is already
>  defined that you shouldn't reproduce in your code.
>  
>  
> -19) Editor modelines and other cruft
> -------------------------------------
> +Editor modelines and other cruft
> +--------------------------------
>  
>  Some editors can interpret configuration information embedded in source files,
>  indicated with special markers.  For example, emacs interprets lines marked
> @@ -1121,8 +1121,8 @@ own custom mode, or may have some other magic method for making indentation
>  work correctly.
>  
>  
> -20) Inline assembly
> --------------------
> +Inline assembly
> +---------------
>  
>  In architecture-specific code, you may need to use inline assembly to interface
>  with CPU or platform functionality.  Don't hesitate to do so when necessary.
> @@ -1153,8 +1153,8 @@ the next instruction in the assembly output:
>  	     : /* outputs */ : /* inputs */ : /* clobbers */);
>  
>  
> -21) Conditional Compilation
> ----------------------------
> +Conditional Compilation
> +-----------------------
>  
>  Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c
>  files; doing so makes code harder to read and logic harder to follow.  Instead,
> @@ -1202,8 +1202,8 @@ expression used.  For instance:
>  	#endif /* CONFIG_SOMETHING */
>  
>  
> -22) Do not crash the kernel
> ----------------------------
> +Do not crash the kernel
> +-----------------------
>  
>  In general, the decision to crash the kernel belongs to the user, rather
>  than to the kernel developer.
> @@ -1264,8 +1264,8 @@ Use BUILD_BUG_ON() for compile-time assertions
>  The use of BUILD_BUG_ON() is acceptable and encouraged, because it is a
>  compile-time assertion that has no effect at runtime.
>  
> -Appendix I) References
> -----------------------
> +References
> +----------
>  
>  The C Programming Language, Second Edition
>  by Brian W. Kernighan and Dennis M. Ritchie.

-- 
Jani Nikula, Intel

Re: [PATCH 1/9] CodingStyle: make Documentation/CodingStyle into symlink

[Alexey Dobriyan]

On Sat, May 10, 2025 at 04:05:29AM -0600, Jonathan Corbet wrote:
> Alexey Dobriyan <adobriyan@gmail.com> writes:
> 
> > Every time I open Documentation/CodingStyle it says the party moved
> > somewhere else. :-(
> >
> > Of course, I forget where it moved to by the next time.
> >
> > Signed-off-by: Alexey Dobriyan <adobriyan@gmail.com>
> > ---
> 
> No 0/9 cover letter?

Not really. Cover letter would be very short:

	Tweak coding style to add things I've learned over the years of
	Linux/C programming.

	And stop making kernel devs look like aliens from another Universe
	(see static_assert() rule and especially(!) "declare ALAP" rule)

> Just FYI, I won't apply coding-style patches without a strong sense that
> there is a consensus behind them...I suspect that could prove to be a
> high bar here.

I split them like referendum ballots to see where the consensus at and
not have big single discussion thread.

Re: [PATCH 8/9] CodingStyle: tell people how to split long "for" loops

[Alexey Dobriyan]

On Sat, May 10, 2025 at 07:56:03PM +0100, David Laight wrote:
> On Fri,  9 May 2025 23:34:29 +0300
> Alexey Dobriyan <adobriyan@gmail.com> wrote:
> 
> > Signed-off-by: Alexey Dobriyan <adobriyan@gmail.com>
> > ---
> >  Documentation/process/coding-style.rst | 16 +++++++++++++++-
> >  1 file changed, 15 insertions(+), 1 deletion(-)
> > 
> > diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
> > index e17de69845ff..494ab3201112 100644
> > --- a/Documentation/process/coding-style.rst
> > +++ b/Documentation/process/coding-style.rst
> > @@ -183,7 +183,21 @@ Descendants are always substantially shorter than the parent and
> >  are placed substantially to the right.  A very commonly used style
> >  is to align descendants to a function open parenthesis.
> >  
> > -These same rules are applied to function headers with a long argument list.
> > +These same rules are applied to function prototypes with a long argument list.
> > +
> > +Very long ``for`` loops are split at the ``;`` characters making it easier
> > +to see which code goes to which clause:
> > +
> > +.. code-block:: c
> > +
> > +	for (int i = 0;
> > +	     i < N;
> > +	     i += 1)
> > +	{
> > +	}
> > +
> > +Opening curly is placed on a separate line then to make it easier to tell
> > +loop body from iteration clause.
> 
> Is that actually the style - I don't remember seeing it.

Check include/linux/list.h.

The point here is that it is either 1 line or 3 (not 2).
If you start splitting for loop there are 2 obvious points to do so.

> The location of the { isn't a significant problem with for (;;), it can be
> much worse elsewhere.
> In reality the 'align with the (' is what causes the problems, either
> double indenting (two tabs) or half indent (4 spaces - to annoy anyone who
> sets an editor to 4 space tabs) is more readable.
> 
> For for (;;) loops I'll normally try moving the initialisation outside the
> loop

That's slightly bad -- variables could leak outside.

> and even put an inverted condition inside the loop to avoid long lines.

> If a #define all bets are off :-)

It applies even more inside #define: #define shits everything by 1 indent usually
so more chance of split line,
it is harder tom see semicolons because macro body is usually colored in
1 color not the normal way.

Do you like how xas_for_each() look like?
"for" macros in include/linux/list.h look mostly OK.

Re: [PATCH 9/9] CodingStyle: flip the rule about curlies

[Jeff Johnson]

On 5/9/2025 11:18 PM, Greg KH wrote:
> On Fri, May 09, 2025 at 11:34:30PM +0300, Alexey Dobriyan wrote:
>> Require set of curlies {} in all if/else branches and all loops
>> not matter how simple.
> 
> Sorry, but no, we are not going to change this long-term coding style
> rule for no real reason at this point in time.

Is the infamous Apple SSL bug (CVE-2014-1266) a good reason?

Re: [PATCH 9/9] CodingStyle: flip the rule about curlies

[Greg KH]

On Mon, May 12, 2025 at 09:43:10AM -0700, Jeff Johnson wrote:
> On 5/9/2025 11:18 PM, Greg KH wrote:
> > On Fri, May 09, 2025 at 11:34:30PM +0300, Alexey Dobriyan wrote:
> >> Require set of curlies {} in all if/else branches and all loops
> >> not matter how simple.
> > 
> > Sorry, but no, we are not going to change this long-term coding style
> > rule for no real reason at this point in time.
> 
> Is the infamous Apple SSL bug (CVE-2014-1266) a good reason?

One bug in 2014 will require us to touch 30+ million lines of code?

Please be reasonable.

And everyone, remember _why_ we have a coding style.  It's not so much
the specifics of _what_ the coding style is, it's the fact that we have
one at all.  Don't argue the specifics of the coding style without a
really really good reason why, with real details and proof.

It took us a long time to increase the default line length, and that too
is still argued about for very good and valid reasons.  That was
discussed in detail, not just thrown at us like this patch series was.

thanks,

greg k-h

Re: [PATCH 1/9] CodingStyle: make Documentation/CodingStyle into symlink

[Greg KH]

On Mon, May 12, 2025 at 07:08:53PM +0300, Alexey Dobriyan wrote:
> On Sat, May 10, 2025 at 04:05:29AM -0600, Jonathan Corbet wrote:
> > Alexey Dobriyan <adobriyan@gmail.com> writes:
> > 
> > > Every time I open Documentation/CodingStyle it says the party moved
> > > somewhere else. :-(
> > >
> > > Of course, I forget where it moved to by the next time.
> > >
> > > Signed-off-by: Alexey Dobriyan <adobriyan@gmail.com>
> > > ---
> > 
> > No 0/9 cover letter?
> 
> Not really. Cover letter would be very short:
> 
> 	Tweak coding style to add things I've learned over the years of
> 	Linux/C programming.
> 
> 	And stop making kernel devs look like aliens from another Universe
> 	(see static_assert() rule and especially(!) "declare ALAP" rule)

Both of those are not valid reasons to change coding style, sorry.
Again, learn about _why_ we have one, don't get bogged down in the
details of _what_ it is.

sorry,

greg k-h

Re: [PATCH 8/9] CodingStyle: tell people how to split long "for" loops

[Greg KH]

On Mon, May 12, 2025 at 07:20:23PM +0300, Alexey Dobriyan wrote:
> On Sat, May 10, 2025 at 07:56:03PM +0100, David Laight wrote:
> > On Fri,  9 May 2025 23:34:29 +0300
> > Alexey Dobriyan <adobriyan@gmail.com> wrote:
> > 
> > > Signed-off-by: Alexey Dobriyan <adobriyan@gmail.com>
> > > ---
> > >  Documentation/process/coding-style.rst | 16 +++++++++++++++-
> > >  1 file changed, 15 insertions(+), 1 deletion(-)
> > > 
> > > diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
> > > index e17de69845ff..494ab3201112 100644
> > > --- a/Documentation/process/coding-style.rst
> > > +++ b/Documentation/process/coding-style.rst
> > > @@ -183,7 +183,21 @@ Descendants are always substantially shorter than the parent and
> > >  are placed substantially to the right.  A very commonly used style
> > >  is to align descendants to a function open parenthesis.
> > >  
> > > -These same rules are applied to function headers with a long argument list.
> > > +These same rules are applied to function prototypes with a long argument list.
> > > +
> > > +Very long ``for`` loops are split at the ``;`` characters making it easier
> > > +to see which code goes to which clause:
> > > +
> > > +.. code-block:: c
> > > +
> > > +	for (int i = 0;
> > > +	     i < N;
> > > +	     i += 1)
> > > +	{
> > > +	}
> > > +
> > > +Opening curly is placed on a separate line then to make it easier to tell
> > > +loop body from iteration clause.
> > 
> > Is that actually the style - I don't remember seeing it.
> 
> Check include/linux/list.h.

That is a complex #define, not a "normal" for loop.

greg k-h

Re: [PATCH 8/9] CodingStyle: tell people how to split long "for" loops

[David Laight]

On Mon, 12 May 2025 19:20:23 +0300
Alexey Dobriyan <adobriyan@gmail.com> wrote:

> On Sat, May 10, 2025 at 07:56:03PM +0100, David Laight wrote:
> > On Fri,  9 May 2025 23:34:29 +0300
> > Alexey Dobriyan <adobriyan@gmail.com> wrote:
> >   
> > > Signed-off-by: Alexey Dobriyan <adobriyan@gmail.com>
> > > ---
> > >  Documentation/process/coding-style.rst | 16 +++++++++++++++-
> > >  1 file changed, 15 insertions(+), 1 deletion(-)
> > > 
> > > diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
> > > index e17de69845ff..494ab3201112 100644
> > > --- a/Documentation/process/coding-style.rst
> > > +++ b/Documentation/process/coding-style.rst
> > > @@ -183,7 +183,21 @@ Descendants are always substantially shorter than the parent and
> > >  are placed substantially to the right.  A very commonly used style
> > >  is to align descendants to a function open parenthesis.
> > >  
> > > -These same rules are applied to function headers with a long argument list.
> > > +These same rules are applied to function prototypes with a long argument list.
> > > +
> > > +Very long ``for`` loops are split at the ``;`` characters making it easier
> > > +to see which code goes to which clause:
> > > +
> > > +.. code-block:: c
> > > +
> > > +	for (int i = 0;
> > > +	     i < N;
> > > +	     i += 1)
> > > +	{
> > > +	}
> > > +
> > > +Opening curly is placed on a separate line then to make it easier to tell
> > > +loop body from iteration clause.  
> > 
> > Is that actually the style - I don't remember seeing it.  
> 
> Check include/linux/list.h.
> 
> The point here is that it is either 1 line or 3 (not 2).
> If you start splitting for loop there are 2 obvious points to do so.

Yes, and there is absolutely no reason to always use both of them.
You do want to split at 'low priority' operators rather than just at
80 columns - but that is always true.

	David
 

	David

Re: [PATCH 1/9] CodingStyle: make Documentation/CodingStyle into symlink

[Al Viro]

On Mon, May 12, 2025 at 07:08:53PM +0300, Alexey Dobriyan wrote:

> I split them like referendum ballots to see where the consensus at and
> not have big single discussion thread.

Just in case - consensus would look like a lot of replies in support and not
simply the lack of replies, right?

Re: [PATCH 1/9] CodingStyle: make Documentation/CodingStyle into symlink

[Alexey Dobriyan]

On Mon, May 12, 2025 at 06:57:49PM +0200, Greg KH wrote:
> On Mon, May 12, 2025 at 07:08:53PM +0300, Alexey Dobriyan wrote:
> > On Sat, May 10, 2025 at 04:05:29AM -0600, Jonathan Corbet wrote:
> > > Alexey Dobriyan <adobriyan@gmail.com> writes:
> > > 
> > > > Every time I open Documentation/CodingStyle it says the party moved
> > > > somewhere else. :-(
> > > >
> > > > Of course, I forget where it moved to by the next time.
> > > >
> > > > Signed-off-by: Alexey Dobriyan <adobriyan@gmail.com>
> > > > ---
> > > 
> > > No 0/9 cover letter?
> > 
> > Not really. Cover letter would be very short:
> > 
> > 	Tweak coding style to add things I've learned over the years of
> > 	Linux/C programming.
> > 
> > 	And stop making kernel devs look like aliens from another Universe
> > 	(see static_assert() rule and especially(!) "declare ALAP" rule)
> 
> Both of those are not valid reasons to change coding style, sorry.

Please read individual items.

I never liked cover letters because they don't get captured in
the commit messages so why bother.

> Again, learn about _why_ we have one,

> don't get bogged down in the details of _what_ it is.

CodingStyle is quite detailed at the moment.
Especially if some new details decreate bug rate a little.

Re: [PATCH 1/9] CodingStyle: make Documentation/CodingStyle into symlink

[Alexey Dobriyan]

On Tue, May 13, 2025 at 05:12:49AM +0100, Al Viro wrote:
> On Mon, May 12, 2025 at 07:08:53PM +0300, Alexey Dobriyan wrote:
> 
> > I split them like referendum ballots to see where the consensus at and
> > not have big single discussion thread.
> 
> Just in case - consensus would look like a lot of replies in support and not
> simply the lack of replies, right?

Well, it is l-k, so absence of NAKs counts as OK.

Re: [PATCH 4/9] CodingStyle: mention "typedef struct S {} S;" if typedef is used

[Alexey Dobriyan]

On Sat, May 10, 2025 at 08:18:53AM +0200, Greg KH wrote:
> On Fri, May 09, 2025 at 11:34:25PM +0300, Alexey Dobriyan wrote:
> > Signed-off-by: Alexey Dobriyan <adobriyan@gmail.com>
> > ---
> >  Documentation/process/coding-style.rst | 14 ++++++++++++++
> >  1 file changed, 14 insertions(+)
> 
> We can't take patches without any changelog text, sorry.

The changelog is in the patch itself but OK.

Re: [PATCH 4/9] CodingStyle: mention "typedef struct S {} S;" if typedef is used

[Alexey Dobriyan]

On Sat, May 10, 2025 at 12:47:19PM +0200, Mauro Carvalho Chehab wrote:
> Em Fri,  9 May 2025 23:34:25 +0300
> Alexey Dobriyan <adobriyan@gmail.com> escreveu:
> 
> > Signed-off-by: Alexey Dobriyan <adobriyan@gmail.com>
> > ---
> >  Documentation/process/coding-style.rst | 14 ++++++++++++++
> >  1 file changed, 14 insertions(+)
> > 
> > diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
> > index ac9c1dbe00b7..5c5902a0f897 100644
> > --- a/Documentation/process/coding-style.rst
> > +++ b/Documentation/process/coding-style.rst
> > @@ -443,6 +443,20 @@ EVER use a typedef unless you can clearly match one of those rules.
> >  In general, a pointer, or a struct that has elements that can reasonably
> >  be directly accessed should **never** be a typedef.
> >  
> > +If you must use ``typedef`` consider using identical names for both the type
> > +and its alias so that the type can be forward declared if necessary:
> 
> Better not, as symbols with duplicated names will generate a Sphinx warning (*). 
> 
> (*) It shouldn't, but there is a pending issue on Sphinx since version 3.1
>     still not addressed:
> 
> 	https://github.com/sphinx-doc/sphinx/pull/8313

OMG, so we are at mercy of static checkers _and_ documentation system? now

I've realised, changelog is bady worded:

Some people invent styles when typedef'ing struct/union:

	typedef struct xxx_s {} xxx;
	typedef struct _xxx {} xxx;

There is no reason to do that, just typedef to exact same name.

Re: [PATCH 6/9] CodingStyle: recommend static_assert/_Static_assert

[Alexey Dobriyan]

On Sat, May 10, 2025 at 08:21:01AM +0200, Greg KH wrote:
> On Fri, May 09, 2025 at 11:34:27PM +0300, Alexey Dobriyan wrote:
> > Linux's BUG_ON is done backwards (condition is inverted).
> > But it is a long story.
> > 
> > However C11/C23 allow to partially transition to what all normal
> > programmers are used to, namely assert().
> > 
> > Deprecate BUILD_BUG_ON, recommend static_assert/_Static_assert.
> > And then some day BUG_ON will be flipped as well.
> 
> Odd, why are you attempting to make all of these mandates without
> actually changing the code itself first?

If I do source code first, some people or checkpatch.pl will say code is
not conformant!

I want to codify rules so my patches don't rejected due to silly
reasons, due to the rules which don't make sense.

> That's just asking for major churn for no good reason...

Reason is there.

static_assert() is better because it is in the standard, and
Linux convention of inverting condition never made any sense.

> Sorry, but this series makes no sense to me.

Re: [PATCH 1/9] CodingStyle: make Documentation/CodingStyle into symlink

[Al Viro]

On Tue, May 13, 2025 at 09:33:34PM +0300, Alexey Dobriyan wrote:
> On Tue, May 13, 2025 at 05:12:49AM +0100, Al Viro wrote:
> > On Mon, May 12, 2025 at 07:08:53PM +0300, Alexey Dobriyan wrote:
> > 
> > > I split them like referendum ballots to see where the consensus at and
> > > not have big single discussion thread.
> > 
> > Just in case - consensus would look like a lot of replies in support and not
> > simply the lack of replies, right?
> 
> Well, it is l-k, so absence of NAKs counts as OK.

In your reality - perhaps...

BTW, somebody ought to inject a bit of reality into the ridiculous wikipedia
page on LKML.  Starting with
	* a lot of developers are not and had not been subscribed to it
for decades.  That includes Linus, among other people.
	* those of us who still are subscribed to it have to choose between
reading through literally thousands of postings and dropping most of them
unread.
	* an l-k posting not Cc'd to saner lists and/or specific people 
is quite likely to be missed.

So absense of NAKs on l-k may or may not count as "OK" from your point of
view, but it does not mean that there is any kind of consensus.  

More to the point, if your... suggestions would go into D/CodingStyle,
replying to objections along the lines of "where the hell has that come
from and when have I agreed to that?" with "why haven't you replied
when I posted them to l-k?" is *NOT* likely to be well-received.

Re: [PATCH 9/9] CodingStyle: flip the rule about curlies

[Alexey Dobriyan]

On Mon, May 12, 2025 at 06:56:56PM +0200, Greg KH wrote:
> On Mon, May 12, 2025 at 09:43:10AM -0700, Jeff Johnson wrote:
> > On 5/9/2025 11:18 PM, Greg KH wrote:
> > > On Fri, May 09, 2025 at 11:34:30PM +0300, Alexey Dobriyan wrote:
> > >> Require set of curlies {} in all if/else branches and all loops
> > >> not matter how simple.
> > > 
> > > Sorry, but no, we are not going to change this long-term coding style
> > > rule for no real reason at this point in time.
> > 
> > Is the infamous Apple SSL bug (CVE-2014-1266) a good reason?

Indeed.

Thanks, curlies were inspired by this CVE but I forgot to mention it.

> One bug in 2014 will require us to touch 30+ million lines of code?

Nobody is proposing to reformat 30 mil lines at one commit
(as much as I'd like it).

Old code will stay old, new code will be formatted per new rules.

> Please be reasonable.

I'm very reasonable. Each patch details rationale why specific style is
better.

> And everyone, remember _why_ we have a coding style.  It's not so much
> the specifics of _what_ the coding style is,

What? When was the last time you read it? It is very much about specifics:
8 spaces, opening curly on the same line except at function scope,
80 columns, recent rule about to format function attributes.

It could have even more specific if there is pre-commit hook forcing
formatting like commercial companies do.

> one at all.  Don't argue the specifics of the coding style without a
> really really good reason why, with real details and proof.

What is "really really good"?

How do you know when it is good reason or not?

I think I have good reason: I programmed a little in another languages
where some of the rules don't apply. In particular C++/Rust don't have
a rule about declaring variables upfront. Nor does any popular programming
language designed in the last 35 years (?).

Such experience made me realize that linux-kernel CodingStyle in this
regard is pointless at best and counter-productive. It was so obvious.

> It took us a long time to increase the default line length, and that too
> is still argued about for very good and valid reasons.

It still 80 columns in CodingStyle.

> That was discussed in detail, not just thrown at us like this patch series was.

Oh come on. In Russia we say "not my first year of marriage".

One of the unwritten rules of linux-kernel is to NEVER post [RFC]
as it will be ignored, but to post a [PATCH] and Cc specific people
to force a discussion.

I don't want to look like a thief who sneaks in occasional declaration
in the middle of a function or set of curlies and get yelled by compilers
or maintainers (especially those armed with checkpatch.pl).

I'll codify this first in CodingStyle, then delete relevant checks from
checkpatch.pl (citing CodingStyle of course).

Re: [PATCH 1/9] CodingStyle: make Documentation/CodingStyle into symlink

[Alexey Dobriyan]

On Tue, May 13, 2025 at 08:04:29PM +0100, Al Viro wrote:
> On Tue, May 13, 2025 at 09:33:34PM +0300, Alexey Dobriyan wrote:
> > On Tue, May 13, 2025 at 05:12:49AM +0100, Al Viro wrote:
> > > On Mon, May 12, 2025 at 07:08:53PM +0300, Alexey Dobriyan wrote:
> > > 
> > > > I split them like referendum ballots to see where the consensus at and
> > > > not have big single discussion thread.
> > > 
> > > Just in case - consensus would look like a lot of replies in support and not
> > > simply the lack of replies, right?
> > 
> > Well, it is l-k, so absence of NAKs counts as OK.
> 
> In your reality - perhaps...

Well, if nobody objects strongly, and maintainer agrees, then patch goes in.
And if patch went in, then it everyone else's problem to undo it?

Right?

> So absense of NAKs on l-k may or may not count as "OK" from your point of
> view, but it does not mean that there is any kind of consensus.  

Sure, but I can't force everyone to reply or vote so it is always
blurry.

Right now it is clear that Greg objects but I personally think
his counter-argument is weak.

He is basically saying that LOC count is too much so Linux should stick
to how things were always have been even if "old style" is objectively
inferior.

> More to the point, if your... suggestions would go into D/CodingStyle,
> replying to objections along the lines of "where the hell has that come
> from and when have I agreed to that?" with "why haven't you replied
> when I posted them to l-k?" is *NOT* likely to be well-received.

Al, this is not Debian where they vote so everyone knows when and
how everyone agreed to something.

If you wake up one day and see "struct inode" renamed to "Inode",
you have all the rights in the world to be upset about everything up
to and including not being in Cc.

Re: [PATCH 6/9] CodingStyle: recommend static_assert/_Static_assert

[David Laight]

On Fri,  9 May 2025 23:34:27 +0300
Alexey Dobriyan <adobriyan@gmail.com> wrote:

> Linux's BUG_ON is done backwards (condition is inverted).
> But it is a long story.
> 
> However C11/C23 allow to partially transition to what all normal
> programmers are used to, namely assert().
> 
> Deprecate BUILD_BUG_ON, recommend static_assert/_Static_assert.
> And then some day BUG_ON will be flipped as well.

_Static_assert() is broken by design and only usable for trival tests.
clang also output the entire expansion of the conditional (even when
a message is specified) which can lead to very very very very long lines.

It isn't at all suitable for many of the checks in the kernel.

Look at the signedness test in min() as an example.

	David

Re: [PATCH 5/9] CodingStyle: institute better inline assembly formatting

[David Laight]

On Fri,  9 May 2025 23:34:26 +0300
Alexey Dobriyan <adobriyan@gmail.com> wrote:

> Signed-off-by: Alexey Dobriyan <adobriyan@gmail.com>
> ---
>  Documentation/process/coding-style.rst | 40 +++++++++++++++++++++-----
>  1 file changed, 33 insertions(+), 7 deletions(-)
> 
> diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
> index 5c5902a0f897..63c41125e713 100644
> --- a/Documentation/process/coding-style.rst
> +++ b/Documentation/process/coding-style.rst
> @@ -1159,16 +1159,42 @@ You may need to mark your asm statement as volatile, to prevent GCC from
>  removing it if GCC doesn't notice any side effects.  You don't always need to
>  do so, though, and doing so unnecessarily can limit optimization.
>  
> -When writing a single inline assembly statement containing multiple
> -instructions, put each instruction on a separate line in a separate quoted
> -string, and end each string except the last with ``\n\t`` to properly indent
> -the next instruction in the assembly output:
> +Inline assembly statements are formatted as follows:
>  
>  .. code-block:: c
>  
> -	asm ("magic %reg1, #42\n\t"
> -	     "more_magic %reg2, %reg3"
> -	     : /* outputs */ : /* inputs */ : /* clobbers */);
> +	asm [volatile] (
> +		"insn1 r0, r1, r2\n\t"
> +		"insn2 r0, 1\n\t"
> +		: /* possibly empty output list */
> +		: /* possibly empty input list */
> +		: /* possibly empty clobber list */
> +		[: goto label list]
> +	);
> +
> +All keywords are placed on a single line.

Have you been reading too many Microsoft documents?

	David

Re: [PATCH 1/9] CodingStyle: make Documentation/CodingStyle into symlink

[Al Viro]

On Tue, May 13, 2025 at 10:26:12PM +0300, Alexey Dobriyan wrote:

> Right now it is clear that Greg objects but I personally think
> his counter-argument is weak.
> 
> He is basically saying that LOC count is too much so Linux should stick
> to how things were always have been even if "old style" is objectively
> inferior.

Objectively by which metrics?  You are trying to force your personal
preferences upon everybody else, doing that on a list most of us
are not even subscribed to.

You are trying to change an equivalent of build artifact, without
bothering to change the source it is derived from.  That file is
*not* a mechanism for changing reality; it codifies the existing
general agreement between the states of wetware in developers.
And if you are interested in changing these states of wetware,
l-k is the wrong place for that.

Re: [PATCH 1/9] CodingStyle: make Documentation/CodingStyle into symlink

[Jonathan Corbet]

Alexey Dobriyan <adobriyan@gmail.com> writes:

> I never liked cover letters because they don't get captured in
> the commit messages so why bother.

FWIW, if a cover letter contains useful information, I capture it in a
merge commit that brings in the rest.  I think I'm far from the only one
who does that...

jon

Re: [PATCH 9/9] CodingStyle: flip the rule about curlies

[Jeff Johnson]

On 5/13/2025 12:06 PM, Alexey Dobriyan wrote:
> On Mon, May 12, 2025 at 06:56:56PM +0200, Greg KH wrote:
>> On Mon, May 12, 2025 at 09:43:10AM -0700, Jeff Johnson wrote:
>>> On 5/9/2025 11:18 PM, Greg KH wrote:
>>>> On Fri, May 09, 2025 at 11:34:30PM +0300, Alexey Dobriyan wrote:
>>>>> Require set of curlies {} in all if/else branches and all loops
>>>>> not matter how simple.
>>>>
>>>> Sorry, but no, we are not going to change this long-term coding style
>>>> rule for no real reason at this point in time.
>>>
>>> Is the infamous Apple SSL bug (CVE-2014-1266) a good reason?
> 
> Indeed.
> 
> Thanks, curlies were inspired by this CVE but I forgot to mention it.
> 
>> One bug in 2014 will require us to touch 30+ million lines of code?
> 
> Nobody is proposing to reformat 30 mil lines at one commit
> (as much as I'd like it).
> 
> Old code will stay old, new code will be formatted per new rules.
> 
>> Please be reasonable.
> 
> I'm very reasonable. Each patch details rationale why specific style is
> better.
> 
>> And everyone, remember _why_ we have a coding style.  It's not so much
>> the specifics of _what_ the coding style is,
> 
> What? When was the last time you read it? It is very much about specifics:
> 8 spaces, opening curly on the same line except at function scope,
> 80 columns, recent rule about to format function attributes.
> 
> It could have even more specific if there is pre-commit hook forcing
> formatting like commercial companies do.
> 
>> one at all.  Don't argue the specifics of the coding style without a
>> really really good reason why, with real details and proof.
> 
> What is "really really good"?
> 
> How do you know when it is good reason or not?
> 
> I think I have good reason: I programmed a little in another languages
> where some of the rules don't apply. In particular C++/Rust don't have
> a rule about declaring variables upfront. Nor does any popular programming
> language designed in the last 35 years (?).
> 
> Such experience made me realize that linux-kernel CodingStyle in this
> regard is pointless at best and counter-productive. It was so obvious.
> 
>> It took us a long time to increase the default line length, and that too
>> is still argued about for very good and valid reasons.
> 
> It still 80 columns in CodingStyle.
> 
>> That was discussed in detail, not just thrown at us like this patch series was.
> 
> Oh come on. In Russia we say "not my first year of marriage".
> 
> One of the unwritten rules of linux-kernel is to NEVER post [RFC]
> as it will be ignored, but to post a [PATCH] and Cc specific people
> to force a discussion.
> 
> I don't want to look like a thief who sneaks in occasional declaration
> in the middle of a function or set of curlies and get yelled by compilers
> or maintainers (especially those armed with checkpatch.pl).
> 
> I'll codify this first in CodingStyle, then delete relevant checks from
> checkpatch.pl (citing CodingStyle of course).

I replied only this patch in the series because, when I first started
programming using the Linux Coding Style in 2004, the single statement brace
rule was the only rule I disagreed with. And that was in part due to the fact
that, at three of my previous employers, the C coding style had dictated
mandatory use of braces. So the explicit prohibition of braces for single
statement conditionals really surprised me.

And note the rule, as written, is not what actually seems to be enforced (at
least by checkpatch.pl). What seems to be enforced is to not use braces where
the conditional is a single line and there is a single line statement. In
other words, if either the conditional or the single statement span multiple
lines, then braces are allowed (or encouraged?). As examples, checkpatch.pl
does not complain about any of the following (either to recommend adding
braces or removing braces):

	if (a_really_long_line_function_name(a_really_long_identifier) ||
	    another_really_long_function_name(another_long_identifier)) {
		braced();
	}

	if (a_really_long_line_function_name(a_really_long_identifier) ||
	    another_really_long_function_name(another_long_identifier))
		not_braced();

	if (a)
		call_a_really_long_function(with_long_argument,
					    another_log_argument);

	if (a) {
		call_a_really_long_function(with_long_argument,
					    another_log_argument);
	}

I'll also note that the popular style guide published by Michael Barr as well
as the MISRA C standard also dictate braces (but I'll admit that both of these
have other rules which contradict the Linux style and where I agree with the
Linux style).

All of that said, ultimately, the Coding Style is supposed to be enforce
consistent style that is readable and maintainable. I get that. I personally
believe that requiring braces makes the code more maintainable, and doesn't
detract from readability. However I'm also agree that changing the rule would
need to eventually lead to changing all the code that doesn't conform (since
one of the reasons for having a style is to have consistency), so I'm also
swayed by admonition to not "argue the specifics of the coding style without a
really really good reason why, with real details and proof," so I'll let
others have their say.

/jeff

Re: [PATCH 1/9] CodingStyle: make Documentation/CodingStyle into symlink

[Pavel Machek]

[-- Attachment #1: Type: text/plain, Size: 352 bytes --]

Hi!

> Every time I open Documentation/CodingStyle it says the party moved
> somewhere else. :-(
> 
> Of course, I forget where it moved to by the next time.

Yes please. I was hiting this way too often, too.

Best regards,
								Pavel

-- 
I don't work for Nazis and criminals, and neither should you.
Boycott Putin, Trump, and Musk!

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 195 bytes --]