[PATCH] D126512: [Docs] Clarify the guideline on omitting braces

[Owen Pan via Phabricator via llvm-commits]

owenpan created this revision.
owenpan added reviewers: erichkeane, lattner, mehdi_amini.
owenpan added a project: LLVM.
Herald added a project: All.
owenpan requested review of this revision.
Herald added a subscriber: llvm-commits.

While working on a clang-format option `RemoveBracesLLVM` that removes braces following the guideline, we were unsure about what to do with the braces of do-while loops. (See D126157#inline-1209965 <https://reviews.llvm.org/D126157#inline-1209965>.) The ratio of //using// to //omitting// the braces is about 4:1 in the llvm-project source, so it will help to add an example to the guideline.

Also clarifies on //complex single-statement body// and make it specific and objective as `RemoveBracesLLVM` does not remove braces if the statement can't fit on a single line.


Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D126512

Files:
  llvm/docs/CodingStandards.rst


Index: llvm/docs/CodingStandards.rst
===================================================================
--- llvm/docs/CodingStandards.rst
+++ llvm/docs/CodingStandards.rst
@@ -1584,22 +1584,23 @@
 Don't Use Braces on Simple Single-Statement Bodies of if/else/loop Statements
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-When writing the body of an ``if``, ``else``, or loop statement, we prefer to
-omit the braces to avoid unnecessary line noise. However, braces should be used
-in cases where the omission of braces harm the readability and maintainability
-of the code.
+When writing the body of an ``if``, ``else``, or for/while loop statement, we
+prefer to omit the braces to avoid unnecessary line noise. However, braces
+should be used in cases where the omission of braces harm the readability and
+maintainability of the code.
 
 We consider that readability is harmed when omitting the brace in the presence
 of a single statement that is accompanied by a comment (assuming the comment
 can't be hoisted above the ``if`` or loop statement, see below).
-Similarly, braces should be used when a single-statement body is complex enough
-that it becomes difficult to see where the block containing the following
-statement began. An ``if``/``else`` chain or a loop is considered a single
-statement for this rule, and this rule applies recursively.
 
-This list is not exhaustive, for example, readability is also harmed if an
+Similarly, braces should be used when a single-statement body can't fit on a
+single line; otherwise, it would be difficult to see where the block containing
+the following statement began. An ``if``/``else`` chain or a loop is considered
+a single statement for this rule, and this rule applies recursively.
+
+This list is not exhaustive. For example, readability is also harmed if an
 ``if``/``else`` chain does not use braced bodies for either all or none of its
-members, with complex conditionals, deep nesting, etc. The examples below
+members, or has complex conditionals, deep nesting, etc. The examples below
 intend to provide some guidelines.
 
 Maintainability is harmed if the body of an ``if`` ends with a (directly or
@@ -1628,9 +1629,8 @@
 
   // Use braces on the outer `if` to avoid a potential dangling else situation.
   if (isa<VarDecl>(D)) {
-    for (auto *A : D.attrs())
-      if (shouldProcessAttr(A))
-        handleAttr(A);
+    if (shouldProcessAttr(A))
+      handleAttr(A);
   }
 
   // Use braces for the `if` block to keep it uniform with the else block.
@@ -1650,6 +1650,13 @@
     for (auto *A : D.attrs())
       handleAttr(A);
 
+  // Use braces for a `do-while` loop and its enclosing statement.
+  if (Tok->is(tok::l_brace)) {
+    do {
+      Tok = Tok->Next;
+    } while (Tok);
+  }
+
   // Use braces for the outer `if` since the nested `for` is braced.
   if (isa<FunctionDecl>(D)) {
     for (auto *A : D.attrs()) {


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D126512.432409.patch
Type: text/x-patch
Size: 2935 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20220527/b76c8053/attachment.bin>