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"

From LibreCAD wiki
Jump to: navigation, search
(Put in Category:Developers)
m (Code style guide: grammar, syntax, format)
Line 1: Line 1:
 
== Code style guide ==
 
== Code style guide ==
  
'''Accessor naming:'''
+
'''Accessor naming'''<br/>
 
+
use:
<pre>use foo->layer()
+
<pre>foo->layer()
 
</pre>
 
</pre>
 
instead of
 
instead of
Line 11: Line 11:
  
  
'''Immutables:'''
+
'''Immutables'''<br/>
Are immutables must be created 'valid', throw an exception if a immutable is attempted to be created that is invalid.
+
All immutables must be created 'valid', throw an exception on an attempted to create an invalid immutable:
 
+
example:
+
 
<pre>
 
<pre>
 
Circle::Circle(Coordinate const& center, double radius) : _center(center), _radius(radius) {
 
Circle::Circle(Coordinate const& center, double radius) : _center(center), _radius(radius) {
Line 21: Line 19:
 
     }
 
     }
 
}
 
}
 
All variables in a immutable class must be declared as const
 
 
</pre>
 
</pre>
 +
All variables in an immutable class must be declared as const.
  
'''Exceptions:'''
 
 
Only throw exceptions in rare situations that are effectively unreasonable.
 
  
''For example:''
+
'''Exceptions'''
  
 +
Only throw where code is effectively unreasonable:
 
<pre>
 
<pre>
document->entityByID(...); // return null if a entry does not exists
+
document->entityByID(...); // return null if an entry does not exists
 
</pre>
 
</pre>
  
  
'''hide shared_ptr behind a typedef:'''
+
'''Variable naming'''
 +
 
 +
Use typedefs to shorten otherwise difficult to read names:
  
 
<pre>
 
<pre>
Line 42: Line 39:
 
     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:
This so we can 'shorten' our shred pointers, example:
+
  
 
<pre>
 
<pre>
   std::list<std::shared_ptr<const Circle>> myListLong; // Less readble
+
   std::list<std::shared_ptr<const Circle>> myListVeryLong; // very long
   std::list<Circle_CSPtr> myListReadable; // better readable
+
   std::list<Circle_CSPtr> myList; // better readable
 
</pre>
 
</pre>
  
  
'''Shared pointer passing:'''
+
'''Shared pointers'''
  
never pass shared_ptr by reference:
+
Never pass a shared_ptr by reference.
  
 
Good:
 
Good:
Line 62: Line 58:
 
Bad:
 
Bad:
 
<pre>
 
<pre>
Line::Line(geo::Coordinate const& start, geo::Coordinate const& end, Layer_SPtr const &layer) : CADEntity(layer), Vector(start, end) {..}
+
Line::Line(geo::Coordinate const& start, geo::Coordinate const& end, Layer_SPtr const & layer) : CADEntity(layer), Vector(start, end) {..}
 
</pre>
 
</pre>
 +
<br/>
 +
'''Namespace std'''
  
'''using namespace std;'''
+
Don't bring in the 'std' namespace into global; always use '''std::'''vector, '''std::'''map, '''std::'''string etc...
  
Don't bring in the std namespace into global. So  always use std::vector, std::map, std::string etc...
 
  
'''Variable declarations on separate lines'''
+
'''Variable declarations'''
  
For readability we prefer to have variables declared on separate lines.
+
Declare variables on separate lines to make them easier to read and to annotate.
This will make commenting on variables when needed easer and in general add to readability.
+
  
good style:
+
Good:
 
<pre>
 
<pre>
const Coordinate _extensionPoint1;
+
const Coordinate _extensionPoint1; // check dependencies...
const Coordinate _extensionPoint2;
+
const Coordinate _tangentPoint2;
 
</pre>
 
</pre>
  
bad style:
+
Bad:
 
<pre>
 
<pre>
const Coordinate _extension_point1, _extension_point2;
+
const Coordinate _extension_point1, _tangentPoint2; // which one did I want?
 
</pre>
 
</pre>
 
+
<br/>
 
'''Const variables '''
 
'''Const variables '''
Const modifier must be added after the variable type:
+
 
 +
You must add const modifiers ''after'' the variable type.
 +
 
 
Good:
 
Good:
 
<pre>
 
<pre>
Line::Line(geo::Coordinate const& start, geo::Coordinate const& end, Layer_SPtr const layer) : CADEntity(layer), Vector(start, end) {..}
+
Line::Line(geo::Coordinate const& start, geo::Coordinate const & end, Layer_SPtr const layer) : CADEntity(layer), Vector(start, end) {..}
 
</pre>
 
</pre>
  
 
Bad:
 
Bad:
 
<pre>
 
<pre>
Line::Line(geo::Coordinate const & start, geo::Coordinate const & end, Layer_SPtr const &layer) : CADEntity(layer), Vector(start, end) {..}
+
Line::Line(geo::Coordinate const & start, const geo::Coordinate& end, Layer_SPtr const layer) : CADEntity(layer), Vector(start, end) {..}
 
</pre>
 
</pre>
 +
<br/>
 +
'''Camel case'''
  
'''Use Camel case '''
+
Use it as much as possible, though some exceptions are allowed:
Try to use camel case as much as possible
+
* 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';
Some exceptions:
+
* Underscores can help make function names autological, e.g. on_dimRadial_changed:
* Variable names in a class can start with a underscore
+
* add a _ (underscore) if the variable name get's unreadable, for example this is ok Dimension_CSptr  
+
* Function names to add clarification for example on_dimRadial_changed. where 'on' and 'changed' are not part of the variable name dimRadial but they are there to notify something.
+
  
 
Good:
 
Good:
Line 116: Line 113:
 
   void on_dim_radial_change() {...};
 
   void on_dim_radial_change() {...};
 
</pre>
 
</pre>
 +
<br/>
 +
'''Class names always start with an Upper-case letter'''
  
'''Class name's always start with a upper case letter'''
+
'''Variable names always starts with a lower-case letter'''
 
+
<br/>
'''Variable name's always starts with a lower case letter'''
+
<br/>
 
+
 
[[Category:Developers]]
 
[[Category:Developers]]

Revision as of 20:18, 4 January 2017

Code style guide

Accessor naming
use:

foo->layer()

instead of

 foo->getLayer();


Immutables
All immutables must be created 'valid', throw an exception on an attempted 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:

    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

Never pass a shared_ptr by reference.

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, geo::Coordinate const& end, Layer_SPtr const  &  layer) : CADEntity(layer), Vector(start, end) {..}


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 starts with a lower-case letter