... | ... | @@ -17,6 +17,32 @@ There are cases when it is hard to write tests for some functions. For example, |
|
|
|
|
|
If writing a unit test is hard or impossible, a developer should consider that the code may have a bad design. Restructuring the code can sometimes allow testing at least selected parts.
|
|
|
|
|
|
# General
|
|
|
|
|
|
## Line length
|
|
|
|
|
|
The project kicked off in 2019. FullHD is ubiquitous with large 4K displays are getting common. In the general case, the code should have no more than 128 columns. This is let developers display two panels side by side. In some exceptional cases (such as URL), the code may be extended to 160 columns, but this should be rare occurrence.
|
|
|
|
|
|
## User Interface (UI) Guidelines
|
|
|
|
|
|
- The minimum resolution needed to reasonably use Stork UI is 720p (1280x720).
|
|
|
- Other aspects are TBD
|
|
|
|
|
|
## Imported Code
|
|
|
|
|
|
If you import code from another project, try to continue the style of the imported project if changes need to be made. This is for two reasons, one is to make merging future versions easier. The other is the encouragement of submitting changes upstream.
|
|
|
|
|
|
## Guidelines Adopted by Other Projects
|
|
|
|
|
|
Other projects have their own coding guidelines. Here're some
|
|
|
examples of such guidelines. These are reference purposes only;
|
|
|
unless explicitly stated we also adopt some part of other guidelines,
|
|
|
they are not part of the Stork's coding guidelines.
|
|
|
|
|
|
* Google: https://google.github.io/styleguide/cppguide.html
|
|
|
* Mozilla: https://firefox-source-docs.mozilla.org/code-quality/coding-style/index.html
|
|
|
* XORP: https://fossies.org/linux/xorp/devnotes/coding-style.txt
|
|
|
|
|
|
# Documentation
|
|
|
|
|
|
## Testing/Documentation addresses and prefixes
|
... | ... | @@ -235,129 +261,3 @@ Examples from PrimeNG: |
|
|
- `ui-tooltip-arrow` - class name for an arrow in tooltip
|
|
|
- `ui-panel-titlebar` - class name for a titlebar in a panel
|
|
|
- `ui-widget-content` - class name of widget content |
|
|
|
|
|
# General
|
|
|
|
|
|
Use all all-lowercase characters for file names. Use dash as a separator (e.g. stork-agent.go). This is consistent with the current practice in kea. Not mixing lower/upper cases will also help avoid name conflicts in a case insensitive file system, such as MacOS.
|
|
|
|
|
|
## Line length
|
|
|
|
|
|
The project kicked off in 2019. FullHD is ubiquitous with large 4K displays are getting common. In the general case, the code should have no more than 128 columns. This is let developers display two panels side by side. In some exceptional cases (such as URL), the code may be extended to 160 columns, but this should be rare occurrence.
|
|
|
|
|
|
## Naming
|
|
|
|
|
|
Don't start things with underscores.
|
|
|
|
|
|
Class names are '''`LikeThis`''', methods are '''`likeThis()`''', variables are '''`like_this`''', and constants are '''`LIKE_THIS`'''. Data class members are '''`like_this_`'''.
|
|
|
|
|
|
## Comments
|
|
|
|
|
|
Multiline comments can be written in C++ or C style (that is, with // or /* */ marks).
|
|
|
|
|
|
```cpp
|
|
|
/*
|
|
|
* This is a comment. It is important probably.
|
|
|
*/
|
|
|
```
|
|
|
|
|
|
```cpp
|
|
|
//
|
|
|
// This is a comment. It is important probably.
|
|
|
//
|
|
|
```
|
|
|
|
|
|
```cpp
|
|
|
/* This is also ok. */
|
|
|
|
|
|
// As is this.
|
|
|
```
|
|
|
|
|
|
Comments at the end of lines should usually be C++ style:
|
|
|
|
|
|
```cpp
|
|
|
class Foo {
|
|
|
int bar_length; // The length of the bar in millimeters.
|
|
|
};
|
|
|
```
|
|
|
|
|
|
### Doxygen Comment Style
|
|
|
|
|
|
When writing a Doxygen special comment block there are several possible styles:
|
|
|
|
|
|
http://www.stack.nl/~dimitri/doxygen/docblocks.html
|
|
|
|
|
|
Doxygen keywords should be prepended with @, not with a backslash. The reason to prefer @ is that backslash may confuse scripts that would go over the code. There is some inconsistency in this regard. There are large parts of older code that still use backslash. It is a matter of personal taste to keep consistency with what is in the file vs. strictly sticking with this principle.
|
|
|
|
|
|
We use the C++ style of 3-slashes:
|
|
|
|
|
|
```cpp
|
|
|
/// A lot of examples are called foo().
|
|
|
///
|
|
|
/// @param baz foo() usually takes an argument
|
|
|
void
|
|
|
foo(Bar baz) {
|
|
|
...
|
|
|
}
|
|
|
```
|
|
|
|
|
|
Make sure inserting a blank line between two function/method
|
|
|
declarations or definitions:
|
|
|
```cpp
|
|
|
class Bad {
|
|
|
/// @brief Short description for bad1
|
|
|
void bad1();
|
|
|
/// @brief Short description for bad2, which may also look for bad1().
|
|
|
void bad2();
|
|
|
};
|
|
|
```
|
|
|
|
|
|
```cpp
|
|
|
class Good {
|
|
|
/// @brief Short description for good1
|
|
|
void good1();
|
|
|
|
|
|
/// @brief Short description for good2, which should be much clearer.
|
|
|
void good2();
|
|
|
};
|
|
|
```
|
|
|
|
|
|
### Explicit @brief for Doxygen
|
|
|
|
|
|
If you don't use @brief as the first thing in your doxygen comment, then doxygen will turn the first paragraph into a @brief description anyway. However, we include it anyway so that everybody understands that this is the @brief description.
|
|
|
|
|
|
## Methods and Functions
|
|
|
|
|
|
### Exception-safe getters and string-production methods
|
|
|
|
|
|
Unless there's a compelling reason to do so neither member value getter methods nor and string-production methods, such as toString(), should throw exceptions. Normally a class member is prevented from ever having an invalid value so there is arguably a getter never has a reason to throw, and string-production methods should always be safe to invoke once a class has been instantiated. Both types of methods are commonly used as log statement arguments where one should not have to worry about catching exceptions.
|
|
|
|
|
|
## Log Statement Safety
|
|
|
|
|
|
It is extremely important to examine all arguments passed into a log
|
|
|
statement to ensure they will produce safe values at runtime:
|
|
|
- Can the argument (or any part of it) be NULL? If so is this taken into account?
|
|
|
- If the argument invokes any functions, are they exception safe?
|
|
|
- If it involves indirection, does this always resolve into a usable value?
|
|
|
- If it raises an exception, is the exception caught? This includes double errors, i.e., log statements in an exception handler.
|
|
|
|
|
|
Log statements are less than helpful if they cause the program to segfault or throw.
|
|
|
|
|
|
# User Interface (UI) Guidelines
|
|
|
|
|
|
- The minimum resolution needed to reasonably use Stork UI is 720p (1280x720).
|
|
|
- Other aspects are TBD
|
|
|
|
|
|
# Imported Code
|
|
|
|
|
|
If you import code from another project, try to continue the style of the imported project if changes need to be made. This is for two reasons, one is to make merging future versions easier. The other is the encouragement of submitting changes upstream.
|
|
|
|
|
|
# Guidelines Adopted by Other Projects
|
|
|
|
|
|
Other projects have their own coding guidelines. Here're some
|
|
|
examples of such guidelines. These are reference purposes only;
|
|
|
unless explicitly stated we also adopt some part of other guidelines,
|
|
|
they are not part of the Stork's coding guidelines.
|
|
|
|
|
|
* Google: https://google.github.io/styleguide/cppguide.html
|
|
|
* Mozilla: https://firefox-source-docs.mozilla.org/code-quality/coding-style/index.html
|
|
|
* XORP: https://fossies.org/linux/xorp/devnotes/coding-style.txt |