[PATCH/RFC] Documenation update: use of braces in if/else if/else chain

[PATCH/RFC] Documenation update: use of braces in if/else if/else chain

[Leila Muhtasib]

Signed-off-by: Leila Muhtasib <muhtasib@gmail.com>
---
Does the below more accruately represent the coding guidelines?
I can modify it, if it doesn't.

Thanks,
Leila


 Documentation/CodingGuidelines |   23 ++++++++++++++++++++---
 1 files changed, 20 insertions(+), 3 deletions(-)

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 4557711..ea90521 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -117,9 +117,26 @@ For C programs:
 
    is frowned upon.  A gray area is when the statement extends
    over a few lines, and/or you have a lengthy comment atop of
-   it.  Also, like in the Linux kernel, if there is a long list
-   of "else if" statements, it can make sense to add braces to
-   single line blocks.
+   it.  Also, like in the Linux kernel, if one of the
+   "if/else if/else" chain has a multiple statement block, use {}
+   even for a single statement block in that chain. And "else"
+   should come on the same line as the closing "}" of its "if" block.
+
+	//correct
+	if (bla) {
+		x = 1;
+		...
+	} else {
+		x = 2;
+	}
+
+	//incorrect
+	if (bla) {
+		x = 1;
+		...
+	}
+	else
+		x = 2;
 
  - We try to avoid assignments inside if().
 
-- 
1.7.7.5 (Apple Git-26)

Re: [PATCH/RFC] Documenation update: use of braces in if/else if/else chain

[Jonathan Nieder]

Hi,

Leila Muhtasib wrote:

> --- a/Documentation/CodingGuidelines
> +++ b/Documentation/CodingGuidelines
> @@ -117,9 +117,26 @@ For C programs:
>  
>     is frowned upon.  A gray area is when the statement extends
>     over a few lines, and/or you have a lengthy comment atop of
> -   it.  Also, like in the Linux kernel, if there is a long list
> -   of "else if" statements, it can make sense to add braces to
> -   single line blocks.
> +   it.  Also, like in the Linux kernel, if one of the
> +   "if/else if/else" chain has a multiple statement block, use {}
> +   even for a single statement block in that chain. And "else"
> +   should come on the same line as the closing "}" of its "if" block.

I don't think that's quite accurate.  Current best practice in both
git and the Linux kernel is a little looser than that.

> +
> +	//correct
> +	if (bla) {
> +		x = 1;
> +		...
> +	} else {
> +		x = 2;
> +	}

True.

> +
> +	//incorrect
> +	if (bla) {
> +		x = 1;
> +		...
> +	}
> +	else
> +		x = 2;

Also true.  But:

	/* correct */
	if (bla) {
		x = 1;
		...
	} else
		x = 2;

And:

If you have a long "if" with a one-line "else", consider whether you
are needlessly keeping the reader in suspense about something simple.
It might be more pleasant to read with the exceptional case up front:

	if (!bla) {
		x = 2;
	} else {
		x = 1;
		...
	}

This is especially true when the exceptional case returns or exits.

	if (bla && no_bla)
		return error("--blah and --no-blah cannot be used together");
	x = 1;
	...

Hope that helps,
Jonathan

Re: [PATCH/RFC] Documenation update: use of braces in if/else if/else chain

[Leila]

On Sun, Jun 10, 2012 at 4:22 PM, Jonathan Nieder <jrnieder@gmail.com> wrote:
> Also true.  But:
>
>        /* correct */
>        if (bla) {
>                x = 1;
>                ...
>        } else
>                x = 2;
>

According to a discussion on my patch, this was cited (not in ref to my code):
Junio C Hamano <gitster@pobox.com> a écrit :

Two points on style (also appear elsewhere in this patch):

       if (!"applying") {
               ...
       } else {
               state->rebase_in_progress = 1;
       }

 - "else" comes on the same line as closing "}" of its "if" block;

 - if one of if/else if/else chain has multiple statement block, use {}
  even for a single statement block in the chain.


So I opened this documentation patch to gain consensus around this
issue, and update the docs accordingly. Depending on the agreement
reached, I can modify the wording of the patch. I don't need to site
the linux Kernel part, I can just say what is supported in this
project.


I think we should still keep this part of the patch:

+    And "else"
+   should come on the same line as the closing "}" of its "if" block.


> And:
>
> If you have a long "if" with a one-line "else", consider whether you
> are needlessly keeping the reader in suspense about something simple.
> It might be more pleasant to read with the exceptional case up front:
>
>        if (!bla) {
>                x = 2;
>        } else {
>                x = 1;
>                ...
>        }
>
> This is especially true when the exceptional case returns or exits.
>
>        if (bla && no_bla)
>                return error("--blah and --no-blah cannot be used together");
>        x = 1;
>        ...

Agreed!

Thanks,
Leila