Merge pull request #16924 from DaveTBlake/docsKeepFormat

[docs]Update code guidelines for readability of setting table-like structures

1 files changed, 20 insertions, 0 deletions

diff --git a/docs/CODE_GUIDELINES.md b/docs/CODE_GUIDELINES.md
index 479e2f25a0..7298d75ccc 100644
--- a/docs/CODE_GUIDELINES.md
+++ b/docs/CODE_GUIDELINES.md
@@ -244,6 +244,26 @@ void Test();
 void Test(void);
 ```
 
+### 3.7. Exceptions to the Formating Rules For Beter Readability
+There are some special situations where vertical alignment and longer lines does greatly aid readability, for example the initialization of some table-like multiple row structures. In these **rare** cases exceptions can be made to the formatting rules on vertical alignment, and the defined line length can be exceeded. 
+
+The layout can be protected from being reformatted when `clang-format` is applied by adding `// clang-format off` and `// clang-format on` statements either side of the lines of code.
+For example
+```
+// clang-format off
+static const CGUIDialogMediaFilter::Filter filterList[] = {
+  { "movies",       FieldTitle,         556,    SettingType::String,  "edit",   "string",   CDatabaseQueryRule::OPERATOR_CONTAINS },
+  { "movies",       FieldRating,        563,    SettingType::Number,  "range",  "number",   CDatabaseQueryRule::OPERATOR_BETWEEN },
+  { "movies",       FieldUserRating,    38018,  SettingType::Integer, "range",  "integer",  CDatabaseQueryRule::OPERATOR_BETWEEN },
+  ...
+  { "songs",        FieldSource,        39030,  SettingType::List,    "list",   "string",   CDatabaseQueryRule::OPERATOR_EQUALS },
+};  
+// clang-format on
+ ```
+The other code guidelines will still need to be applied within the delimited lines of code, but with `clang-format` off care will be needed to check these manually. Using vertical alignment means that sometimes the entire block of code may need to be realigned, good judgement should be used in each case with the objective of preserving readability yet minimising impact.
+ 
+This is to be used with discretion, marking large amounts of code to be left unformatted by `clang-format` without reasonable justification will be rejected.
+
 **[back to top](#table-of-contents)**
 
 ## 4. Statements