Created Coding Standards (mediawiki)
AnHardt
parent
cdaeaf96b7
commit
c6e2d57be1
1 changed files with 170 additions and 0 deletions
170
Coding-Standards.mediawiki
Normal file
170
Coding-Standards.mediawiki
Normal file
|
|
@ -0,0 +1,170 @@
|
|||
!!!OUTDATED!!! At the moment we use astyle.
|
||||
|
||||
|
||||
Please follow these coding standards for contributing code to Marlin. Pull requests which fail to follow good coding standards may be postponed for cleanup.
|
||||
|
||||
== Coding Style ==
|
||||
=== Indentation ===
|
||||
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, 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
|
||||
}
|
||||
}
|
||||
</pre>
|
||||
|
||||
=== 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.
|
||||
|
||||
* "One True Bracket" Style – "1TBS" – to rule them all
|
||||
* Almost all opening braces at the end of lines, including declarations:
|
||||
<pre>
|
||||
if (...) {
|
||||
...
|
||||
}
|
||||
else {
|
||||
...
|
||||
}
|
||||
</pre>
|
||||
* Closing braces should always align with the starting column of the opening line
|
||||
|
||||
=== Spacing ===
|
||||
|
||||
* One space between keywords and their conditions:<br /><code>if (…)</code>, <code>while (…)</code>, <code>do {…} while(…)</code> etc.
|
||||
* No space between functions and their arguments:<br /><code>myFunction(…);</code>
|
||||
* Spaces between operators, most of the time:<br /><code>myVar = aVar + bVar * cVar;</code><br /><code>myVal = (a*b + b*c); // grouping</code>
|
||||
|
||||
=== Comments ===
|
||||
|
||||
* Doxygen-style headings (documenting in .h files), C++ single-line style // for under 3 lines
|
||||
* Multi-line use asterisks in the second column
|
||||
|
||||
== Names and Symbols ==
|
||||
=== Capitalization ===
|
||||
|
||||
* <code>your_function_name(int in_integer, float in_float=0.0)</code>
|
||||
* <code>MyClass</code>
|
||||
* <code>ClassMethod</code>
|
||||
* <code>classData</code>
|
||||
* <code>local_variable</code>
|
||||
* <code>global_variable</code>
|
||||
* <code>MACRO_NAME</code> – anything created with <code>#define</code>
|
||||
* <code>EnumeratedType</code>
|
||||
|
||||
=== Filenames ===
|
||||
|
||||
* use <code>.cpp</code> for C++ sources
|
||||
* use <code>.c</code> for C only sources
|
||||
* use <code>.h</code> for headers of all types
|
||||
|
||||
=== Directories ===
|
||||
* Lowercase names.
|
||||
* Note that Arduino cannot (easily) compile code in a sketch subfolder
|
||||
|
||||
=== Libraries ===
|
||||
|
||||
Whenever possible use functions supplied by avr-libc or Arduino bundled libraries. Any libraries required to compile Marlin should be included in the package so that they are guaranteed to be compatible versions.
|
||||
|
||||
== Extended Language Features ==
|
||||
|
||||
Marlin is written in C/C++ and must be able to compile with the supplied Makefile and an up-to-date version of Arduino. Backward-compatibility to earlier versions of Arduino is not required, but we can deal with this on an issue-to-issue basis.
|
||||
|
||||
=== Primitive Types ===
|
||||
|
||||
* On AVR both <code>int</code> and <code>short</code> are 16-bits, and <code>long</code> is 32 bits.
|
||||
|
||||
=== Memory Usage ===
|
||||
|
||||
* DO NOT use dynamic memory allocations such as <code>malloc()</code>, <code>free()</code>, <code>new</code>, <code>delete</code>
|
||||
* ''(Some exceptions may be considered, with caveats!)''
|
||||
|
||||
=== No Extended Features ===
|
||||
|
||||
* DO NOT use extended C++ features like:
|
||||
* Exceptions (throw / catch)
|
||||
* Virtual functions / classes
|
||||
* Templates
|
||||
* Standard Template Library (STL)
|
||||
|
||||
=== Avoid Expensive Code ===
|
||||
|
||||
* <code>millis()</code> can be expensive so put it in a <code>uint32_t</code> if you need it more than once.
|
||||
* Pre-calculate if possible instead of calculating on the fly
|
||||
|
||||
== Marlin-specific Conventions ==
|
||||
|
||||
=== Preprocessor directives ===
|
||||
|
||||
* Use <code>#define</code> instead of <code>const</code> for configurable values (for now)
|
||||
* Don't use <code>#if</code> / <code>#endif</code> for commenting-out unused, old or broken code. We have a git repository! If it's obsolete, delete it.
|
||||
* Use <code>#if ENABLED(FEATURE_NAME)</code> / <code>#endif</code> to compile enabled features. (Using these macros allows features to be set externally.)
|
||||
* Use <code>#if DISABLED(FEATURE_NAME)</code> / <code>#endif</code> to compile disabled features. (Using these macros allows features to be set externally.)
|
||||
* Use <code>#define</code> macros to avoid repeating boilerplate code.<br />Consider both readability and maintainability.
|
||||
|
||||
=== Adding a New Feature ===
|
||||
Since Marlin is an Arduino firmware and not a desktop application, much care has been taken to keep code size at a minimum, and to avoid using any features that may overtax the hardware, including demanding math operations. New features should try to conserve the limited resources available and allocate a fixed amount of memory (apart from <code>auto</code> variables) to do their work.
|
||||
|
||||
* <code>#define</code> is used liberally, especially for configuration values
|
||||
* Use <code>#define MYFEATURE</code> for feature switches.
|
||||
* Feature settings have some flexibility, and can have values.
|
||||
* Test features with <code>#if ENABLED(MYFEATURE)</code> / <code>#if DISABLED(MYFEATURE)</code>. (Using these macros allows features to be set externally.)
|
||||
* Indent the code between <code>#if…</code> and <code>#endif</code> for editors that only have naive code-folding.
|
||||
* Add a comment: <code>#endif // MYFEATURE</code> — Only if the <code>#endif</code> is ''far away''!
|
||||
|
||||
==== New Feature Example ====
|
||||
'''In Configuration.h:'''
|
||||
<pre>
|
||||
// Enable this to make something new happen
|
||||
#define MYFEATURE
|
||||
#if ENABLED(MYFEATURE)
|
||||
#define MYFEATURE_SETTING 12.5
|
||||
#undef OVERRIDDEN_FEATURE // This won't be needed with MYFEATURE
|
||||
#endif
|
||||
</pre>
|
||||
'''In SanityCheck.h:'''
|
||||
<pre>
|
||||
/**
|
||||
* My feature
|
||||
*/
|
||||
#if ENABLED(MYFEATURE) && ENABLED(INCOMPAT_FEATURE)
|
||||
#error MYFEATURE is not compatible with INCOMPAT_FEATURE
|
||||
#endif
|
||||
</pre>
|
||||
'''In Conditionals.h:'''
|
||||
<pre>
|
||||
/**
|
||||
* My feature
|
||||
*/
|
||||
#if ENABLED(MYFEATURE)
|
||||
#undef OVERRIDDEN_FEATURE // This feature is disabled by MYFEATURE
|
||||
#undef OVERRIDDEN_SETTING // This setting will always be 1234 with MYFEATURE
|
||||
#define OVERRIDDEN_SETTING 1234
|
||||
#endif
|
||||
</pre>
|
||||
'''In Marlin_main.cpp, for example:'''
|
||||
<pre>
|
||||
// My Feature, when Your Feature is disabled
|
||||
#if ENABLED(MYFEATURE) && DISABLED(YOURFEATURE)
|
||||
my_feature_function(); // Run my feature, possible an inline function taking refs
|
||||
#if ENABLED(HISFEATURE)
|
||||
...
|
||||
call_something();
|
||||
...
|
||||
#else // !HISFEATURE
|
||||
...
|
||||
call_something_else();
|
||||
...
|
||||
#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)
|
||||
Loading…
Add table
Add a link
Reference in a new issue