mirror of
https://github.com/MarlinFirmware/Marlin.git
synced 2024-11-22 18:25:18 +00:00
Destroyed Coding Standards (markdown)
Bo Herrmannsen
parent
4d84a7d3b7
commit
b8fe540d4d
@ -1,195 +0,0 @@
|
||||
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](#coding-style)
|
||||
- [Indentation](#indentation) - Elements that require indentation
|
||||
- [Bracket Style](#bracket-style) - The one true bracket style
|
||||
- [Spacing](#spacing) - No tabs allowed, 2 space indentation, etc.
|
||||
- [Comments](#comments) - Multi-line, single-line…
|
||||
- [Names and Symbols](#names-and-symbols)
|
||||
- [Capitalization](#capitalization)
|
||||
- [Filenames](#filenames)
|
||||
- [Directories](#directories)
|
||||
- [Libraries](#libraries)
|
||||
- [Language Features](#language-features)
|
||||
- [Primitive Types](#primitive-types) – Maybe you know a few
|
||||
- [Memory Usage](#memory-usage) – Static data is mandatory
|
||||
- [Extended Language Features](#extended-language-features) – Don't use them
|
||||
- [Avoid Expensive Code](#avoid-expensive-code) – Arduino is fast, but not _that_ fast
|
||||
- [Marlin-specific Conventions](marlin-specific-conventions)
|
||||
- [Preprocessor Directives](#preprocessor-directives) – Faster compilation, smaller code
|
||||
- [Adding a New Features](#adding-a-new-feature) – Make Marlin better with your own code
|
||||
- [Useful Links](#useful-links)
|
||||
|
||||
## 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 `#if` 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:
|
||||
`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
|
||||
|
||||
## Names and Symbols
|
||||
### Capitalization
|
||||
|
||||
- `your_function_name(int in_integer, float in_float=0.0)`
|
||||
- `MyClass`
|
||||
- `ClassMethod`
|
||||
- `classData`
|
||||
- `local_variable`
|
||||
- `global_variable`
|
||||
- `MACRO_NAME` – anything created with `#define`
|
||||
- `EnumeratedType`
|
||||
|
||||
### 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.
|
||||
|
||||
## 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 `int` and `short` are 16-bits, and `long` is 32 bits.
|
||||
|
||||
### Memory Usage
|
||||
|
||||
- DO NOT use dynamic memory allocations such as
|
||||
`malloc()`, `free()`, `new`, `delete`
|
||||
- _(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
|
||||
|
||||
- `millis()` can be expensive so put it in a `uint32_t` if you need it more than once.
|
||||
- Pre-calculate if possible instead of calculating on the fly
|
||||
|
||||
## Marlin-specific Conventions
|
||||
|
||||
### Preprocessor directives
|
||||
|
||||
- Use `#define` instead of `const` for configurable values (for now)
|
||||
- Don't use `#if` / `#endif` for commenting-out unused, old or broken code. We have a git repository!
|
||||
- Use `#if[[n]def]` / `#endif` to prevent disabled features from compiling.
|
||||
- Use `#define` macros to avoid repeating boilerplate code.
|
||||
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 `auto` variables) to do their work.
|
||||
|
||||
- `#define` is used liberally, especially for configuration values
|
||||
- Use `#define MYFEATURE` for feature switches.
|
||||
- Feature settings have some flexibility, and can have values.
|
||||
- Test features with `#if[n]def` / `#if [!]defined(MYFEATURE)`.
|
||||
- Indent the code between `#if…` and `#endif` for naive code-folding.
|
||||
- Add a comment: `#endif // MYFEATURE` — Only if the `#endif` is _far away_!
|
||||
|
||||
####Example:
|
||||
__In Configuration.h:__
|
||||
```
|
||||
// Enable this to make something new happen
|
||||
#define MYFEATURE
|
||||
#ifdef MYFEATURE
|
||||
#define MYFEATURE_SETTING 12.5
|
||||
#undef OVERRIDDEN_FEATURE // This won't be needed with MYFEATURE
|
||||
#ifdef INCOMPAT_FEATURE
|
||||
#
|
||||
#endif
|
||||
#endif
|
||||
```
|
||||
__In SanityCheck.h:__
|
||||
```
|
||||
/**
|
||||
* My feature
|
||||
*/
|
||||
#if defined(MYFEATURE) && defined(INCOMPAT_FEATURE)
|
||||
#error MYFEATURE is not compatible with INCOMPAT_FEATURE
|
||||
#endif
|
||||
```
|
||||
__In Conditionals.h:__
|
||||
```
|
||||
/**
|
||||
* My feature
|
||||
*/
|
||||
#if defined(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
|
||||
```
|
||||
__In Marlin_main.cpp, for example:__
|
||||
```
|
||||
// My Feature, when Your Feature is disabled
|
||||
#if defined(MYFEATURE) && !defined(YOURFEATURE)
|
||||
my_feature_function(); // Run my feature, possible an inline function taking refs
|
||||
#ifdef HISFEATURE
|
||||
...
|
||||
call_something();
|
||||
...
|
||||
#else // !HISFEATURE
|
||||
...
|
||||
call_something_else();
|
||||
...
|
||||
#endif // !HISFEATURE
|
||||
#endif // MYFEATURE
|
||||
```
|
||||
|
||||
## 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…
Reference in New Issue
Block a user