Coding Standards

Please follow these coding standards for contributing code to Marlin. Pull requests which fail to follow good coding standards may be postponed for cleanup.

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 #if blocks and other non-brace compiler blocks

void myFunction() {
  if (myCondition == 0) {
    #ifdef PETER_PARKER
      slingWeb(100);
    #else
      findPhoneBooth();
    #endif
  }
}

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:

if (...) {
  ...
}
else {
  ...
}

• Closing braces should always align with the starting column of the opening line

Spacing

• One space between keywords and their conditions: if (…), while (…), do {…} while(…) etc.
• No space between functions and their arguments: myFunction(…);
• Spaces between operators, most of the time: myVar = aVar + bVar * cVar; myVal = (a*b + b*c); // grouping

Comments

• Doxygen-style headings (documenting in .h files), C++ single-line style // for under 3 lines
• Multi-line use asterisks in the second column

Capitalization

• ClassMethod
• classData (or class_data?)
• localVar (or local_var?)

Filenames

• use .cpp for C++ sources
• use .c for C only sources
• use .h 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.

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.

• On AVR both int and short are 16-bits, and long is 32 bits.
• DO NOT use dynamic memory allocations such as malloc(), free(), new, delete (some exceptions may be considered)
• DO NOT use extended C++ features like:
  • Exceptions (throw / catch)
  • Virtual functions / classes
  • Templates
  • Standard Template Library (STL)

---

Preprocessor directives

• Use #define instead of const for configurable values
• Don't use #if / #endif for commenting-out unused, old or broken code. We have a git repository to manage such parts of the codebase.
• Use #if / #endif to prevent disabled features from compiling.
• Use #define macros to avoid repeating boilerplate code. Consider both readability and maintainability.

###Marlin-specific Conventions 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.

• #define is used liberally, especially for configuration values
• millis() is expensive so cache it if you need it more than once
• Pre-calculate if possible instead of calculating on the fly

Useful links

• Atmel AVR4027: Tips and Tricks to Optimize Your C Code for 8-bit AVR Microcontrollers