We have moved to https://dokuwiki.librecad.org/
Lots of content was already moved to the new wiki, but there is still work to do. If you want to contribute, please register a new account at https://dokuwiki.librecad.org/
This wiki will be kept for a while to keep search engine results valid. Moved sites may be deleted here in future.
Difference between revisions of "LibreCAD 3 - LibreCAD 3 - code style"
R. van Twisk (Talk | contribs) |
LordOfBikes (Talk | contribs) (added category for wiki revision) |
||
(16 intermediate revisions by 5 users not shown) | |||
Line 1: | Line 1: | ||
== Code style guide == | == Code style guide == | ||
+ | '''Line length'''<br/> | ||
+ | Maximum line length is 120 columns | ||
− | ''' | + | '''Spacing'''<br/> |
+ | * Between if, for, while and ( | ||
+ | * Between comparison operators | ||
+ | * After , | ||
− | < | + | |
+ | '''Indentation'''<br/> | ||
+ | * Namespace blocks | ||
+ | * public and private +1 and methods +2 | ||
+ | |||
+ | '''Headers'''<br/> | ||
+ | * use #pragma once instead of #ifndef | ||
+ | * Include what you use | ||
+ | * Do not use virtual and override in the same declaration | ||
+ | |||
+ | '''Accessor naming'''<br/> | ||
+ | Use: | ||
+ | <pre>foo->layer() | ||
</pre> | </pre> | ||
instead of | instead of | ||
Line 11: | Line 28: | ||
− | '''Immutables | + | '''Immutables'''<br/> |
− | + | All immutables must be created 'valid', throw an exception on an attempt to create an invalid immutable: | |
− | + | ||
− | + | ||
<pre> | <pre> | ||
− | Circle::Circle( | + | Circle::Circle(Coordinate const& center, double radius) : _center(center), _radius(radius) { |
− | if ( | + | if (_radius < 0.0) { |
throw "Invalid radius"; | throw "Invalid radius"; | ||
} | } | ||
− | |||
− | |||
} | } | ||
</pre> | </pre> | ||
+ | All variables in an immutable class must be declared as const. | ||
− | |||
− | + | '''Exceptions''' | |
− | + | ||
− | '' | + | |
+ | Only throw where code is effectively unreasonable: | ||
<pre> | <pre> | ||
− | document->entityByID(...); // return null if | + | document->entityByID(...); // return null if an entry does not exists |
</pre> | </pre> | ||
− | ''' | + | '''Variable naming''' |
+ | |||
+ | Use typedefs to shorten otherwise difficult to read names: | ||
<pre> | <pre> | ||
+ | DECLARE_SHORT_SHARED_PTR(Circle) | ||
+ | |||
+ | // OR | ||
+ | |||
typedef std::shared_ptr<Circle> Circle_SPtr; | typedef std::shared_ptr<Circle> Circle_SPtr; | ||
typedef std::shared_ptr<const Circle> Circle_CSPtr; | typedef std::shared_ptr<const Circle> Circle_CSPtr; | ||
</pre> | </pre> | ||
+ | This can also make further variable-use more legible: | ||
− | + | <pre> | |
+ | std::list<std::shared_ptr<const Circle>> myListVeryLong; // very long | ||
+ | std::list<Circle_CSPtr> myList; // better readable | ||
+ | </pre> | ||
+ | |||
+ | '''Shared pointers''' | ||
+ | |||
+ | Shared pointers should be passed by const reference, they can be passed as value if they are going to be stored in the target (with std::move) | ||
+ | |||
+ | <br/> | ||
+ | '''Namespace std''' | ||
+ | |||
+ | Don't bring in the 'std' namespace into global; always use '''std::'''vector, '''std::'''map, '''std::'''string etc... | ||
+ | |||
+ | |||
+ | '''Variable declarations''' | ||
+ | |||
+ | Declare variables on separate lines to make them easier to read and to annotate. | ||
+ | |||
+ | Good: | ||
<pre> | <pre> | ||
− | + | const Coordinate _extensionPoint1; // check dependencies... | |
− | + | const Coordinate _tangentPoint2; | |
</pre> | </pre> | ||
+ | Bad: | ||
+ | <pre> | ||
+ | const Coordinate _extension_point1, _tangentPoint2; // which one did I want? | ||
+ | </pre> | ||
+ | <br/> | ||
+ | '''Const variables ''' | ||
− | ''' | + | You must add const modifiers ''after'' the variable type. |
+ | |||
+ | Good: | ||
+ | <pre> | ||
+ | Line::Line(geo::Coordinate const& start, geo::Coordinate const & end, Layer_SPtr const layer) : CADEntity(layer), Vector(start, end) {..} | ||
+ | </pre> | ||
+ | |||
+ | Bad: | ||
+ | <pre> | ||
+ | Line::Line(geo::Coordinate const & start, const geo::Coordinate& end, Layer_SPtr const layer) : CADEntity(layer), Vector(start, end) {..} | ||
+ | </pre> | ||
+ | <br/> | ||
+ | '''Camel case''' | ||
− | + | Use it as much as possible, though some exceptions are allowed: | |
+ | * Variable names in a class may start with a underscore; | ||
+ | * An '_' (underscore) may be added if the variable name gets unreadable, e.g. in 'Dimension_CSptr'; | ||
+ | * Underscores can help make function names autological, e.g. on_dimRadial_changed: | ||
Good: | Good: | ||
<pre> | <pre> | ||
− | + | const String _textValue; | |
+ | void on_dimRadial_change() {...}; | ||
</pre> | </pre> | ||
Bad: | Bad: | ||
<pre> | <pre> | ||
− | + | const String _text_value; | |
+ | void on_dim_radial_change() {...}; | ||
</pre> | </pre> | ||
+ | <br/> | ||
+ | '''Class names always start with an Upper-case letter.''' | ||
+ | |||
+ | '''Variable names always start with a lower-case letter.''' | ||
+ | <br/> | ||
+ | <br/> | ||
+ | [[Category:Developers]][[Category:rev-LC3-wiki]] |
Latest revision as of 20:48, 24 April 2019
Code style guide
Line length
Maximum line length is 120 columns
Spacing
- Between if, for, while and (
- Between comparison operators
- After ,
Indentation
- Namespace blocks
- public and private +1 and methods +2
Headers
- use #pragma once instead of #ifndef
- Include what you use
- Do not use virtual and override in the same declaration
Accessor naming
Use:
foo->layer()
instead of
foo->getLayer();
Immutables
All immutables must be created 'valid', throw an exception on an attempt to create an invalid immutable:
Circle::Circle(Coordinate const& center, double radius) : _center(center), _radius(radius) { if (_radius < 0.0) { throw "Invalid radius"; } }
All variables in an immutable class must be declared as const.
Exceptions
Only throw where code is effectively unreasonable:
document->entityByID(...); // return null if an entry does not exists
Variable naming
Use typedefs to shorten otherwise difficult to read names:
DECLARE_SHORT_SHARED_PTR(Circle) // OR typedef std::shared_ptr<Circle> Circle_SPtr; typedef std::shared_ptr<const Circle> Circle_CSPtr;
This can also make further variable-use more legible:
std::list<std::shared_ptr<const Circle>> myListVeryLong; // very long std::list<Circle_CSPtr> myList; // better readable
Shared pointers
Shared pointers should be passed by const reference, they can be passed as value if they are going to be stored in the target (with std::move)
Namespace std
Don't bring in the 'std' namespace into global; always use std::vector, std::map, std::string etc...
Variable declarations
Declare variables on separate lines to make them easier to read and to annotate.
Good:
const Coordinate _extensionPoint1; // check dependencies... const Coordinate _tangentPoint2;
Bad:
const Coordinate _extension_point1, _tangentPoint2; // which one did I want?
Const variables
You must add const modifiers after the variable type.
Good:
Line::Line(geo::Coordinate const& start, geo::Coordinate const & end, Layer_SPtr const layer) : CADEntity(layer), Vector(start, end) {..}
Bad:
Line::Line(geo::Coordinate const & start, const geo::Coordinate& end, Layer_SPtr const layer) : CADEntity(layer), Vector(start, end) {..}
Camel case
Use it as much as possible, though some exceptions are allowed:
- Variable names in a class may start with a underscore;
- An '_' (underscore) may be added if the variable name gets unreadable, e.g. in 'Dimension_CSptr';
- Underscores can help make function names autological, e.g. on_dimRadial_changed:
Good:
const String _textValue; void on_dimRadial_change() {...};
Bad:
const String _text_value; void on_dim_radial_change() {...};
Class names always start with an Upper-case letter.
Variable names always start with a lower-case letter.