Jaye Evins
1c902230fe
* Bulk replaced tabs with spaces * Bulk removed trailing whitespace from lines * Replaced c-style comments with c++-style comments in file banners * Replace nested namespace definitions with single concise definitions (C++17), this keeps the indentation more manageable * Cleanup ordering and spacing of include directives * Bulk renaming of header file extensions from '.h' to '.hpp'. * Update CODING-STYLE.md * Update target_compile_features from cxx_std_11 to cxx_std_20. * Refresh .clang-format file. Still needs a lot of tweaking.
174 lines
4.2 KiB
Markdown
174 lines
4.2 KiB
Markdown
Glabels Coding Style
|
|
====================
|
|
|
|
This file describes the coding style used in all glabels source code. Any
|
|
patches or pull requests should adhere to this style.
|
|
|
|
|
|
Formatting
|
|
----------
|
|
|
|
### Tabs vs. Spaces
|
|
|
|
Use spaces for all code indentation and line-to-line alignment of code elements.
|
|
(e.g. aligning function arguments). This ensures that the code displays
|
|
correctly everywhere.
|
|
|
|
|
|
### Indentation Style
|
|
|
|
Glabels code uses the Allman[^1] style (a.k.a "BSD Style") of code indentation.
|
|
I.e. the brace associated with a control statement is placed on the next line,
|
|
indented to the same level as the control statement. Statements within the
|
|
braces are indented to the next level.
|
|
|
|
```
|
|
while ( condition )
|
|
{
|
|
something();
|
|
somethingElse();
|
|
}
|
|
|
|
if ( condition2 )
|
|
{
|
|
handleCondition2();
|
|
}
|
|
else
|
|
{
|
|
somethingElse();
|
|
}
|
|
```
|
|
|
|
Also applies to function, class and namespace declaration statements.
|
|
|
|
|
|
|
|
### Parenthesis
|
|
|
|
- Never place spaces between a function name and its opening paren.
|
|
- Always place a space between a control statement and its opening paren.
|
|
- Never use parens in return statements when not necessary.
|
|
|
|
|
|
Naming
|
|
------
|
|
|
|
### Type Names
|
|
|
|
- Start with a capital letter.
|
|
- Each new word is capitalized.
|
|
- No underscores.
|
|
|
|
|
|
### Variable Names
|
|
|
|
- Start each variable name with a lowercase letter.
|
|
- Each subsequent word is capitalized.
|
|
- No underscores.
|
|
- Data members start with a lowercase "m" with the 2nd letter capitalized.
|
|
- Use "i" prefix for indexes and "n" prefix for total number of indexes.
|
|
|
|
|
|
### Function names
|
|
|
|
- Start each function name with a lowercase letter.
|
|
- Each subsequent word is capitalized.
|
|
- No underscores.
|
|
|
|
|
|
### Constant Names
|
|
|
|
- TBD (currently not uniform)
|
|
|
|
|
|
Code Organization
|
|
-----------------
|
|
|
|
Generally code is organized into modules. Usually a module defines a single
|
|
class or a small namespace of functions/constants/etc. A module is defined by
|
|
two files: a header file (its specification) and an implementation file.
|
|
Header filenames have a `.hpp` extension[^2] and implementation filenames have a
|
|
`.cpp` extension.
|
|
|
|
|
|
### Self-contained Headers
|
|
|
|
Header files should be self-contained. I.e. they should not require any
|
|
prerequisite includes. To enforce this requirement, an implementation file
|
|
shall include its header file before any other includes.
|
|
|
|
|
|
### Multiple Inclusion Guards
|
|
|
|
All header files should have an ifndef guard to prevent multiple inclusion.
|
|
|
|
```
|
|
#ifndef ns_Module_hpp
|
|
#define ns_Module_hpp
|
|
|
|
...
|
|
|
|
#endif // ns_Module_h
|
|
```
|
|
|
|
|
|
### Include Directives
|
|
|
|
Header files should be included in the following order.
|
|
|
|
1. header file for this module (e.g. this would be `Foo.hpp` in `Foo.cpp`).
|
|
2. Glabels header files.
|
|
3. Qt header files
|
|
3. C++ system header files (e.g. STL files)
|
|
4. C system header files (preference is for the C++ version if available,
|
|
e.g. \<cmath> instead of \<math.h>.
|
|
5. Other libraries' header files
|
|
|
|
Paths used in include directives should always be relative to either the
|
|
glabels source directory or an appropriate base directory for each library.
|
|
They should NEVER include UNIX directory shortcuts such as "." (the current
|
|
directory) or ".." (the parent directory).
|
|
|
|
Angle brackets ("<>") should be used for inclusion of all external header files
|
|
(such as C/C++ and Qt header files). Double quotes should be used for all
|
|
glabels header files.
|
|
|
|
Do not use forward declarations to any external entities. Use the appropriate
|
|
include directives instead.
|
|
|
|
|
|
### Namespaces
|
|
|
|
- Private definitions are placed in unnamed namespaces to limit scope to the current translation unit.
|
|
- All other glabels code is placed in the top-level "glabels" namespace.
|
|
- Nested namespace declarations should follow the more concise C++17 syntax
|
|
```
|
|
namespace glabels::model
|
|
{
|
|
...
|
|
}
|
|
```
|
|
|
|
|
|
Notes
|
|
-----
|
|
|
|
### Emacs
|
|
|
|
The following is an excerpt from my emacs configuration supporting the style
|
|
```
|
|
(defun my-c++-hook ()
|
|
(setq c-default-style "bsd"
|
|
c-basic-offset 8
|
|
indent-tabs-mode nil
|
|
show-trailing-whitespace t))
|
|
|
|
(add-hook 'c++-mode-hook 'my-c++-hook)
|
|
```
|
|
|
|
|
|
References
|
|
----------
|
|
[^1]: https://en.wikipedia.org/wiki/Indent_style#Allman_style
|
|
[^2]: [C++ Weekly - Ep 442 - Stop Using .h For C++ Header Files!](https://www.youtube.com/watch?v=mr3sOT-Delg)
|