[PATCH v2] Documentation/CodingStyle: Add an example for braces

[PATCH v2] Documentation/CodingStyle: Add an example for braces

[Gary R Hook]

Add another example of required braces when using a compound statements.

Signed-off-by: Gary R Hook <gary.hook@amd.com>
---

Changes since v1:
- Move the new example up, and make it more generic

 Documentation/process/coding-style.rst |    9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index a20b44a40ec4..fcef0b4b59d0 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -188,6 +188,15 @@ and
 	else
 		do_that();
 
+Do use braces when a body is more complex than a single simple statement:
+
+.. code-block:: c
+
+	if (condition) {
+		if (another_condition)
+			do_something();
+	}
+
 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:
 

Re: [PATCH v2] Documentation/CodingStyle: Add an example for braces

[Jonathan Corbet]

On Thu, 15 Mar 2018 15:04:02 -0500
Gary R Hook <gary.hook@amd.com> wrote:

> +Do use braces when a body is more complex than a single simple statement:
> +
> +.. code-block:: c
> +
> +	if (condition) {
> +		if (another_condition)
> +			do_something();
> +	}

Somebody is sure to complain at some point that this should really be:

	if (condition && another_condition)
		do_something();

To head that off, I think I'll apply your first version instead, sorry
Jani.

In general I'm pretty reluctant to apply coding-style patches for the
simple reason that I sure don't want to be the arbitrator of proper kernel
style.  This one seems to fit well within the accepted norms, though.

Thanks,

jon

Re: [PATCH v2] Documentation/CodingStyle: Add an example for braces

[Jani Nikula]

On Wed, 21 Mar 2018, Jonathan Corbet <corbet@lwn.net> wrote:
> To head that off, I think I'll apply your first version instead, sorry
> Jani.

No worries.

BR,
Jani.

-- 
Jani Nikula, Intel Open Source Technology Center

Re: [PATCH v2] Documentation/CodingStyle: Add an example for braces

[Gary R Hook]

On 03/22/2018 04:12 AM, Jani Nikula wrote:
> On Wed, 21 Mar 2018, Jonathan Corbet <corbet@lwn.net> wrote:
>> To head that off, I think I'll apply your first version instead, sorry
>> Jani.
> 
> No worries.
> 

Submitting a v3 because the example could better illuminate the options 
by using loop construct inside of an if, addressing Jani's point but 
without opening the door to later criticism.

I also like the verbage in v2/3 better, but I'll let Jonathan make the call.

BTW which tree should these be developed against? I used torvalds, but 
I'm not entirely sure that was the proper one?

Gary

Re: [PATCH v2] Documentation/CodingStyle: Add an example for braces

[Jonathan Corbet]

On Mon, 26 Mar 2018 11:28:03 -0500
Gary R Hook <gary.hook@amd.com> wrote:

> Submitting a v3 because the example could better illuminate the options 
> by using loop construct inside of an if, addressing Jani's point but 
> without opening the door to later criticism.
> 
> I also like the verbage in v2/3 better, but I'll let Jonathan make the call.

As I told you, I was applying the first version; I did that last week.

> BTW which tree should these be developed against? I used torvalds, but 
> I'm not entirely sure that was the proper one?

The MAINTAINERS file will (almost) always answer that question for
you:	

	T:	git git://git.lwn.net/linux.git docs-next

For a patch like this it doesn't matter, since there's is no other work on
the file to conflict with.

THanks,

jon

Re: [PATCH v2] Documentation/CodingStyle: Add an example for braces

[Gary R Hook]

On 03/26/2018 11:32 AM, Jonathan Corbet wrote:
> On Mon, 26 Mar 2018 11:28:03 -0500
> Gary R Hook <gary.hook@amd.com> wrote:
> 
>> Submitting a v3 because the example could better illuminate the options
>> by using loop construct inside of an if, addressing Jani's point but
>> without opening the door to later criticism.
>>
>> I also like the verbage in v2/3 better, but I'll let Jonathan make the call.
> 
> As I told you, I was applying the first version; I did that last week.

Forgive me; was out of the office. I've seen maintainers comment but not 
necessarily execute immediately, and therefore I try to learn how each 
works, but here I made an assumption. No worries and sorry to bother.

> 
>> BTW which tree should these be developed against? I used torvalds, but
>> I'm not entirely sure that was the proper one?
> 
> The MAINTAINERS file will (almost) always answer that question for
> you:	
> 
> 	T:	git git://git.lwn.net/linux.git docs-next

Good point. I should know better by now.

Again, thank you.

Gary