[llvm] [RFC][Docs] Clarify brace omission for single-line bodies (PR #195985)

[Shilei Tian via llvm-commits]

https://github.com/shiltian created https://github.com/llvm/llvm-project/pull/195985

Update the Coding Standards brace guidance to emphasize that braces should be
omitted only for simple bodies that do not wrap across multiple physical lines.


>From 2e4c72eeefc77edbc4e7f1b953e37253bb6af349 Mon Sep 17 00:00:00 2001
From: Shilei Tian <i at tianshilei.me>
Date: Tue, 5 May 2026 22:46:28 -0400
Subject: [PATCH] [RFC][Docs] Clarify brace omission for single-line bodies

Update the Coding Standards brace guidance to emphasize that braces should be
omitted only for simple bodies that do not wrap across multiple physical lines.
---
 llvm/docs/CodingStandards.rst | 31 ++++++++++++++++++++++---------
 1 file changed, 22 insertions(+), 9 deletions(-)

diff --git a/llvm/docs/CodingStandards.rst b/llvm/docs/CodingStandards.rst
index 593388db7ddf2..8b075897bb94a 100644
--- a/llvm/docs/CodingStandards.rst
+++ b/llvm/docs/CodingStandards.rst
@@ -1694,23 +1694,26 @@ faraway places in the file to tell that the function is local:
     ...
   }
 
-Don't Use Braces on Simple Single-Statement Bodies of if/else/loop Statements
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Don't Use Braces on Simple Single-Line Bodies
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 When writing the body of an ``if``, ``else``, or ``for``/``while`` loop
-statement, we aim to reduce unnecessary line noise.
+statement, we aim to reduce unnecessary line noise without hiding control flow.
+Omit braces only when the body is a single simple statement that does not wrap
+onto multiple physical lines.
 
 **Omit braces when:**
 
-*   The body consists of a single **simple** statement.
-*   The single statement is not preceded by a comment.
+*   The body consists of a single simple statement that does not wrap onto
+    multiple physical lines.
+*   The body is not preceded by a comment.
     (Hoist comments above the control statement if you can.)
-*   An ``else`` clause, if present, also meets the above criteria (single
-    simple statement, no associated comments).
+*   Every arm of an ``if``/``else if``/``else`` chain meets the same criteria.
 
 **Use braces in all other cases, including:**
 
 *   Multi-statement bodies
+*   Single-statement bodies that wrap onto multiple physical lines
 *   Single-statement bodies with non-hoistable comments
 *   Complex single-statement bodies (e.g., deep nesting, complex nested
     loops)
@@ -1757,6 +1760,15 @@ The examples below provide guidelines for these cases:
     handleOtherDecl(D);
   }
 
+  // Use braces for both blocks when one block has a single statement that wraps
+  // across multiple lines.
+  if (isa<FunctionDecl>(D)) {
+    handleFunctionDecl(D);
+  } else {
+    handleDeclWithLongName(D,
+                           /*ShouldLog=*/true);
+  }
+
   // Use braces for the `else if` and `else` block to keep it uniform with the
   // `if` block.
   if (isa<FunctionDecl>(D)) {
@@ -1791,12 +1803,13 @@ The examples below provide guidelines for these cases:
     }
   }
 
-  // Use braces on the outer block because there are more than two levels of
+  // Use braces on the outer blocks because there are more than two levels of
   // nesting.
   if (isa<FunctionDecl>(D)) {
-    for (auto *A : D.attrs())
+    for (auto *A : D.attrs()) {
       for (ssize_t i : llvm::seq<ssize_t>(count))
         handleAttrOnDecl(D, A, i);
+    }
   }
 
   // Use braces on the outer block because of a nested `if`; otherwise, the