Explicit Coding Standards for reference

Coding-Standards.mediawiki

@@ -1,53 +1,19 @@
-The formatting of the source code is now controlled by the [[http://astyle.sourceforge.net/astyle.html|astyle]] program. The options which specify the style in use are found in the .astylerc file which is located in the top level folder of this repository. To reformat a file, run astyle --options=.astylerc <file_name>.
+Please follow these formatting guidelines and coding standards when contributing code to Marlin. Pull requests that don't follow good coding standards may be postponed for cleanup.
 
-The current style is specified by these options:
-<pre>
---style=google
---keep-one-line-blocks
- 
---indent=spaces=2
---indent-preproc-block
---indent-preproc-define
---indent-col1-comments
- 
---remove-brackets
---break-after-logical
---delete-empty-lines
- 
---pad-oper
---pad-header
---unpad-paren
---align-pointer=type
---align-reference=type
- 
---attach-classes
---attach-inlines
---keep-one-line-statements
- 
---indent-namespaces
-</pre>
-
-You will need to properly format all files offered for inclusion in our repositories.
-The Travis Integration tool checks for compliance and will reject any submission that is not properly styled.
-
-Do this before committing the file to a git repository.
-
- <!--
 == Coding Style ==
 === Indentation ===
-Indentation is important for readability and maintainability of code.
+Indentation is important for readability and maintainability of code, and provides guidance for naïve code editors (e.g., TextMate, Sublime, et. al.) to properly fold code blocks by level.
 
 * 2 spaces. Don't use tabs at all.
-* All blocks indented, preprocessor (e.g. <code>#if</code>) blocks are indented to the level of their including function
-
+* All blocks indented, including <code>#if</code> blocks and other non-brace compiler blocks
 <pre>
 void myFunction() {
   if (myCondition == 0) {
-#ifdef PETER_PARKER
-    slingWeb(100);
-#else
-    findPhoneBooth();
-#endif
+    #ifdef PETER_PARKER
+      slingWeb(100);
+    #else
+      findPhoneBooth();
+    #endif
   }
 }
 </pre>
@@ -55,7 +21,7 @@ void myFunction() {
 === Bracket-style ===
 We've chosen a bracket (i.e., ''brace'') style that shows the most code lines on screen, and which causes folded code blocks to appear at the end of the line where they begin. If vertical spacing makes code more readable, add a blank line rather than using a different bracket style.
 
-* "google" Style
+* "One True Bracket" Style – "1TBS" – to rule them all
 * Almost all opening braces at the end of lines, including declarations:
 <pre>
 if (...) {
@@ -196,6 +162,6 @@ Since Marlin is an Arduino firmware and not a desktop application, much care has
   #endif // !HISFEATURE
 #endif // MYFEATURE
 </pre>
--->
+
 == Useful links ==
 * [Atmel AVR4027: Tips and Tricks to Optimize Your C Code for 8-bit AVR Microcontrollers](http://www.atmel.com/images/doc8453.pdf)