Differences

This shows you the differences between two versions of the page.

Link to this comparison view

coding-standards [2020/09/02 11:12]
wolfmanjm
coding-standards [2021/02/22 17:47]
Line 1: Line 1:
-Lots of people work together on Smoothie's code. 
- 
-{{page>contributing}} 
- 
-In order to make everybody's life easier, and keep the codebase clean and manageable, here are a few rules you should follow when coding Smoothie stuff : 
- 
-=== Do not include other headers in a header file unless absolutely necessary to define something in that header 
- 
-Un-necessary includes clutter the code, and makes compile time longer. 
- 
-Bad example ( in a .h file ) :  
- 
-<code cpp> 
-#include "Kernel.h" 
-#include "PanelScreen.h" 
-#include "Button.h" 
-#include <array> 
-#include <vector> 
-</code> 
- 
-Instead do: 
-<code cpp> 
-#include <array> 
-#include <vector> 
- 
-class Kernel; 
-class PanelScreen; 
-class Button; 
-</code> 
- 
-However, you still need to include whatever is necessary in your .cpp file 
- 
-=== Use class pointers in classes and use Class xxx in header to forward define it 
- 
-Same thing : no unnecessary includes in .h files: 
- 
-<code cpp> 
-class Robot; 
-class Stepper; 
-class Planner; 
- 
-class Kernel { 
-    public: 
-        Kernel(); 
- 
-        Robot* robot; 
-        Stepper* stepper; 
-        Planner* planner; 
- 
-}; 
-</code> 
- 
-=== Include headers only in cpp files, and only ones that are needed to fully define a class 
- 
-Never include something in the header file ( unless absolutely necessary ). Include it in the .cpp file, and only if it is really required. 
- 
-===  Do not put code in a method in a header unless absolutely necessary 
- 
-the only time this is needed is for time critical code that must be inlined 
- 
-=== Do not use #ifdef in the code ===  
-This is rarely needed and is only currently used by the makefile and main.cpp to eliminate named modules 
- 
-=== Follow C++ practices 
- 
-* class fields should be private, use getters and setters where necessary 
-* methods not needed to be called externally should be private 
-* try not to use multiple inheritance 
-* make destructors virtual 
-* use std::STL where appropriate 
-* use C++11 where appropriate 
- 
-=== Code formatting 
- 
-* 4 spaces per indent, no tabs please 
-* mostly follows linux bracket style http://astyle.sourceforge.net/astyle.html#_style=linux 
- 
-=== Must compile cleanly 
-Your contributed code must compile cleanly with no warnings. 
- 
-=== Test your code!! 
-This is really important. If you make changes to existing code make sure it is thoroughly tested before issuing a pull request. 
-If it is a new feature it should be tested as well as possible, or request testing by pointing to your branch in your repo. 
- 
-=== Keep pull requests small 
-Only one feature or bug fix or refactor should go into a specific pull request, it is very hard to scan a huge pull request and to test it, so keep the 
-changes small and testable. Please follow git flow practices where possible. 
-branches should be called feature/feature-name or fix/fix-name, and only contain changed relevant to that feature or fix. 
-If other changes need to be made that are not directly related to this change but this change relies on them then it should be noted in the pull request that it depends on pull request #xxxx 
- 
-=== Do not use blocking wait loops 
-There must not be any blocking wait loops in the code, there is no RTOS here so a blocking wait loop stops everythign from running, and if long enough will trigger the watchdog timer. In the case of needing to wait for several milliseconds you can use the ''safe_delay_ms'' or ''safe_delay_us'' function call, which will call on_idle() to keep things going. However note this is not an accurate delay. For accurate timing an interupt timer must be used.