Changes between Version 2 and Version 3 of RFC4

Timestamp:

Mar 22, 2017, 5:40:39 PM (7 years ago)

Author:

mloskot

Comment:

First draft

RFC4

@@ -3 +3 @@
 This document proposes and describes desired code formatting style used across C/C++ source code in GEOS.
 
-||RFC 4:     || Code Formatting Style||
-||Author:       || Mateusz Łoskot ||
-||Contact:      || mateusz@loskot.net ||
-||Status:       || Draft ||
+||RFC 4:  ||Code Formatting Style||
+||Author: ||Mateusz Łoskot       ||
+||Contact:||mateusz@loskot.net   ||
+||Status: ||Draft                ||
 
 == Summary ==
 
-This document proposes and describes desired code formatting style used across C/C++ source code in GEOS.
+The document proposes and describes desired default code formatting style guidelines for GEOS programming in C and C++ languages.
+
+The goal of this document is to initiate process to reach an agreement for the default code formatting style.
+
+== Motivation ==
+
+There is a need to decide on format of GEOS source code and apply such globally consistent format to GEOS C/C++ codebase.
+
+A uniform, codebase-wide formatting style makes reading and comprehending existing code easier, writing code focused on important aspects of new developments and more pleasent, removes burden during a patch or pull request code reviews and prevents [http://wiki.c2.com/?WhereDoTheBracesGo bikeshedding religious arguments]. Even in small projects, contributing developers discover the problems of working without an agreed upon code format.
+
+The utility of such guidelines has been proven by many open source software projects.
+
+"A mature engineers know that a standard is more important than which standard." ~[MongoDB]
+
+The scope of the proposal is specifically limited to formatting style guidelines. It is not an intention to develop a general coding guide covering other aspects of writing software like naming, etc.
 
 == Proposal ==
 
-The goal of the proposal is to provide guidelines for the default code style when programming in C/C++ for GEOS.
+It is important to make effortless for developers to produce properly formatted code.
+
+The proposal suggests to use [https://clang.llvm.org/docs/ClangFormat.html clang-format] version 3.8 or higher to define C++ code formatting rules for GEOS code.
+
+The `clang-format` is a tool to automatically format C/C++ code, so that developers don't need to worry about style issues.
+Unlike other tools which use own parsers, `clang-format` uses the Clang tokenizer and supports the same C++ source code as the Clang compiler.
+This guarantees correct output is produced and offers unique features (eg. wrapping long lines whether of code, strings, arrays - something which AStyle has no way of doing).
+
+The style settings are defined in `.clang-format` configuration file for our [https://clang.llvm.org/docs/ClangFormatStyleOptions.html style settings].
+
+The `clang-format` is straightforward to run and can support development workflow as standalone tool or as one of many editor integrations.
+
+Although no means to enforce the default formatting style are proposed, currently used CI services (eg. Travis CI) may be employed as a post-commit safety valve
+- a clang-format lint failure as a compile break (eg. [https://github.com/mongodb/mongo/blob/master/buildscripts/clang_format.py clang_format.py] build script used by MongoDB).
+
+== Code Formatting Rules ==
+
+What code formatting rules to use? 
+
+`clang-format` offers several defaults (eg. LLVM, Mozilla, Linux, Google C++ Style).
+
+The proposal recommends to use one of the base styles, if necessary, fine-tunning as an easier way to get started than deciding on each option one by one. 
+
+The reasons are two-fold:
+* make GEOS code unified with the wide spectrum of well-established C/C++ projects 
+* long arguments and religious wars prevention.
+
+=== `.clang-format` ===
+
+work-in-progress
+
+{{{
+---
+BasedOnStyle:   Mozilla
+Language:       Cpp
+Standard:       Cpp03
+ColumnLimit:    80
+IndentWidth:    4   
+TabWidth:       4   
+UseTab:         Never
+
+BraceWrapping:
+  AfterClass:      true
+  AfterControlStatement: true
+  AfterEnum:       true
+  AfterFunction:   true
+  AfterNamespace:  true
+  AfterObjCDeclaration: true
+  AfterStruct:     true
+  AfterUnion:      true
+  BeforeCatch:     true
+  BeforeElse:      true
+  IndentBraces:    false
+BreakBeforeBinaryOperators: None
+BreakBeforeBraces: Allman
+BreakBeforeTernaryOperators: true
+}}}
+
+=== `.editorconfig` ===
+
+[http://editorconfig.org/ EditorConfig] is currently in use and `.editorconfig` file is provied to automatically tell popular code editors about the basic style settings
+like indentation, whitespaces and end-of-line markers for distinguished types of plain text files.
+
+The `.editorconfig` file will have to be updated to match the chosen `.clang-format` settings.
+
+=== Big Reformat ===
+
+What to do about the existing code?
+
+The proposal recommends to just do one big reformat of the codebase.
+
+While it may seem causing clutter in the repository log (eg. `svn blame`), if it occurs infrequently (eg. yearly) and is applied to the entire codebase at that time, it should not be very disruptive to the source code history. 
+
+Partial application of the code formatting rules would create more work without delivering the full benefit [MongoDB] leading to codebase with different styles mixed.
+
+== Best Practice ==
+
+How to work against the natural entropy in a codebase:
+
+* It is highly recommended to use `clang-format` integration while writing a code.
+* Format changed code before committing or opening pull requests.
+* If you have to commit change in code formatting, do it in separate commit. Avoid commits with a mixture of code and formatting changes.
+** There is downside of history clutter in repository, but this proposal states that a codebase with different styles across is even worse.
+
+== Conclusion ==
+
+"After all, every moment of time wasted on code formatting or discussion thereof is eliminated." ~[MongoDB]
+
+== References ==
+
+* [MongoDB] Succeeding With !ClangFormat: [https://engineering.mongodb.com/post/succeeding-with-clangformat-part-1-pitfalls-and-planning/ Part 1], [https://engineering.mongodb.com/post/succeeding-with-clangformat-part-2-the-big-reformat/ Part 2], [https://engineering.mongodb.com/post/succeeding-with-clangformat-part-3-persisting-the-change/ Part 3]
+* https://clangformat.com - `clang-format` interactive guide and builder
+* https://zed0.co.uk/clang-format-configurator/