On Mon, Jan 16, 2017 at 05:00:14PM -0500, Jeff King wrote:
> > > Please don't. Obviously C treats the "if/else" as a single unit, but
> > > IMHO it's less error-prone to include the braces any time there are
> > > multiple visual lines. E.g., something like:
> > >
> > > while (foo)
> > > if (bar)
> > > one();
> > > else
> > > two();
> > > three();
> > >
> > > is much easier to spot as wrong when you would require braces either
> > > way (and not relevant here, but I'd say that even an inner block with a
> > > comment deserves braces for the same reason).
> >
> > There is no documentation about the preferred coding style.
>
> Documentation/CodingGuidelines says:
>
> - We avoid using braces unnecessarily. I.e.
>
> if (bla) {
> x = 1;
> }
>
> 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.
>
> I think this is pretty clearly the "gray area" mentioned there. Which
> yes, does not say "definitely do it this way", but I hope makes it clear
> that you're supposed to use judgement about readability.
So here's a patch.
I know we've usually tried to keep this file to guidelines and not
rules, but clearly it has not been clear-cut enough in this instance.
-- >8 --
Subject: [PATCH] CodingGuidelines: clarify multi-line brace style
There are some "gray areas" around when to omit braces from
a conditional or loop body. Since that seems to have
resulted in some arguments, let's be a little more clear
about our preferred style.
Signed-off-by: Jeff King <peff@xxxxxxxx>
---
Documentation/CodingGuidelines | 37 ++++++++++++++++++++++++++++++++-----
1 file changed, 32 insertions(+), 5 deletions(-)
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 4cd95da6b..0e336e99d 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -206,11 +206,38 @@ For C programs:
x = 1;
}
- 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.
+ is frowned upon. But there are a few exceptions:
+
+ - When the statement extends over a few lines (e.g., a while loop
+ with an embedded conditional, or a comment). E.g.:
+
+ while (foo) {
+ if (x)
+ one();
+ else
+ two();
+ }
+
+ if (foo) {
+ /*
+ * This one requires some explanation,
+ * so we're better off with braces to make
+ * it obvious that the indentation is correct.
+ */
+ doit();
+ }
+
+ - When there are multiple arms to a conditional, it can make
+ sense to add braces to single line blocks for consistency.
+ E.g.:
+
+ if (foo) {
+ doit();
+ } else {
+ one();
+ two();
+ three();
+ }
- We try to avoid assignments in the condition of an "if" statement.
--
2.11.0.642.gd6f8cda6c