Fix inconsistent namespace formatting guidelines #12982

1. 
   ryanofsky commented at 8:28 pm on April 13, 2018: member

   Suggested formatting for namespaces in the developer guide is currently inconsistent. This commit updates the developer guide and clang-format configuration to consistently put “namespace” and opening/closing braces on the same line. Example:

   0namespace boost {
   1namespace signals2 {
   2class connection;
   3} // namespace signals2
   4} // namespace boost
   

   Currently the Source code organization section has an example like the one above, but the Coding style section example and description put a newline between the opening “namespace foo” and brace (but oddly no newline between closing namespace and brace).

   Avoiding newlines before namespace opening braces makes nested declarations less verbose and also avoids asymmetry with closing braces. It’s also a common style used in our own and other codebases:

   • https://google.github.io/styleguide/cppguide.html#Namespaces
   • https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Coding_Style#Classes
   • https://llvm.org/docs/CodingStandards.html#namespace-indentation
2. Fix inconsistent namespace formatting guidelines

   Suggested formatting for namespaces in the developer guide is currently
   inconsistent. This commit updates the developer guide and clang-format
   configuration to consistently put "namespace" and opening/closing braces
   on the same line. Example:
   
   ```c++
   namespace boost {
   namespace signals2 {
   class connection;
   } // namespace signals2
   } // namespace boost
   ```
   
   Currently the "Source code organization" section has an example like the one
   above, but the "Coding style" section example and description put a newline
   between the opening "namespace foo" and brace (but oddly no newline between
   closing namespace and brace).
   
   Avoiding newlines before namespace opening braces makes nested declarations
   less verbose and also avoids asymmetry with closing braces. It's also a
   common style used in other codebases:
   
   * https://google.github.io/styleguide/cppguide.html#Namespaces
   * https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Coding_Style#Classes
   * https://llvm.org/docs/CodingStandards.html#namespace-indentation

   cd0e1e91dd
3. fanquake added the label Docs on Apr 13, 2018
4. 
   practicalswift commented at 5:21 am on April 14, 2018: contributor

   Concept ACK
5. in src/.clang-format:19 in 681dea1876 outdated

   11@@ -12,7 +12,11 @@ AlwaysBreakBeforeMultilineStrings: false
   12 AlwaysBreakTemplateDeclarations: true
   13 BinPackParameters: false
   14 BreakBeforeBinaryOperators: false
   15-BreakBeforeBraces: Linux
   16+BreakBeforeBraces: Custom
   17+BraceWrapping:
   18+  AfterClass: true
   19+  AfterFunction: true
   20+  AfterStruct: true
   

   ---

   ---

   

   MarcoFalke commented at 1:51 pm on April 14, 2018:

   structs had their braces on the same line previously?

   ---

   

   ryanofsky commented at 2:18 pm on April 14, 2018:

   structs had their braces on the same line previously?

   Good catch, this was a mistake.

6. 
   MarcoFalke commented at 1:54 pm on April 14, 2018: member

   Fine with me, since this seems a common theme, but I feel like the other settings in the clang-format file should not be toggled.
7. ryanofsky force-pushed on Apr 14, 2018
8. ryanofsky force-pushed on Apr 14, 2018
9. ryanofsky force-pushed on Apr 14, 2018
10. 
    ryanofsky commented at 2:20 pm on April 14, 2018: member

    but I feel like the other settings in the clang-format file should not be toggled

    Fixed now, this was a mistake. I misread the documentation which didn’t mention there was difference between classes and structs.

    Updated 681dea1876a079741a6da3a5130f8b7418da2f4e -> cd0e1e91dd6d020263433d85526a91181180471d (pr/namespace.1 -> pr/namespace.2)

11. 
    MarcoFalke commented at 2:59 pm on April 14, 2018: member

    utACK cd0e1e91dd6d020263433d85526a91181180471d
12. 
    Empact commented at 11:49 pm on April 15, 2018: member

    utACK cd0e1e9
13. 
    jnewbery commented at 3:50 pm on April 16, 2018: member

    utACK cd0e1e91dd6d020263433d85526a91181180471d
14. 
    promag commented at 3:58 pm on April 16, 2018: member

    utACK cd0e1e9.
15. MarcoFalke merged this on Apr 17, 2018
16. MarcoFalke closed this on Apr 17, 2018

    ---

17. MarcoFalke referenced this in commit a63b4e3493 on Apr 17, 2018
18. PastaPastaPasta referenced this in commit 4e4aab98db on Jun 17, 2020
19. PastaPastaPasta referenced this in commit e5b434d411 on Jun 27, 2020
20. MarcoFalke locked this on Sep 8, 2021

Contributors
ryanofsky practicalswift MarcoFalke Empact jnewbery promag

Labels
Docs