From 7c637a593d6f7299d8dbbe9c20d6c367d8e335ab Mon Sep 17 00:00:00 2001 From: Kazu Hirata Date: Tue, 21 Oct 2025 15:49:14 -0700 Subject: [PATCH] [Docs] Clarify the brace policy for if/else/loop statements Without this patch, the five-paragraph section is unclear about exactly when to use and not to use braces. Specifically, the first paragraph suggests omitting braces, and then subsequent paragraphs carve out exceptions. At the end, it's unclear what situations remain for omitting braces. This patch overhauls the text for readability. Specifically, it first describes when to omit braces and then lists cases where we should retain braces. --- llvm/docs/CodingStandards.rst | 36 +++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/llvm/docs/CodingStandards.rst b/llvm/docs/CodingStandards.rst index 8677d894a94a6..63f6663d687ea 100644 --- a/llvm/docs/CodingStandards.rst +++ b/llvm/docs/CodingStandards.rst @@ -1692,29 +1692,29 @@ 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -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 harms the readability and -maintainability of the code. +When writing the body of an ``if``, ``else``, or ``for``/``while`` loop +statement, we aim to reduce unnecessary line noise. -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). +**Omit braces when:** -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. +* The body consists of a single **simple** statement. +* The single statement 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). -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, or has complex conditionals, deep nesting, etc. The examples below -intend to provide some guidelines. +**Use braces in all other cases, including:** -Maintainability is harmed if the body of an ``if`` ends with a (directly or -indirectly) nested ``if`` statement with no ``else``. Braces on the outer ``if`` -would help to avoid running into a "dangling else" situation. +* Multi-statement bodies +* Single-statement bodies with non-hoistable comments +* Complex single-statement bodies (e.g., deep nesting, complex nested + loops) +* Inconsistent bracing within ``if``/``else if``/``else`` chains (if one + block requires braces, all must) +* ``if`` statements ending with a nested ``if`` lacking an ``else`` (to + prevent "dangling else") +The examples below provide guidelines for these cases: .. code-block:: c++