|
This page documents some coding guidelines for Kea project.
|
|
This page documents some coding guidelines for Kea project.
|
|
|
|
|
|
see [Stork coding guilelines](https://gitlab.isc.org/isc-projects/stork/-/wikis/Processes/coding-guidelines) for UI related guidelines. Also refer to the [BIND 9 coding guidelines](https://gitlab.isc.org/isc-projects/bind9/-/blob/main/doc/dev/style.md).
|
|
see [Stork coding guilelines](https://gitlab.isc.org/isc-projects/stork/-/wikis/Processes/coding-guidelines) for UI related guidelines. Also refer to the [BIND 9 coding guidelines](https://gitlab.isc.org/isc-projects/bind9/-/blob/main/doc/dev/style.md).
|
|
|
|
|
|
|
|
|
|
|
|
|
|
# Common
|
|
# Common
|
|
|
|
|
|
<details>
|
|
<details>
|
|
<summary>Testing/Documentation addresses and prefixes</summary>
|
|
<summary>Testing/Documentation addresses and prefixes</summary>
|
... | @@ -21,18 +21,18 @@ We sprinkle comments in code with keywords to indicate pending work. |
... | @@ -21,18 +21,18 @@ We sprinkle comments in code with keywords to indicate pending work. |
|
In Kea, @todo is preferred. It should be prepended with triple ///, so it will show up on a nicely auto-generated Doxygen todo list. If there is a corresponding ticket, feel free to specify its number in the comment. Unless other wise specified, issue #1234 means a ticket in the trac, available at http://kea.isc.org.
|
|
In Kea, @todo is preferred. It should be prepended with triple ///, so it will show up on a nicely auto-generated Doxygen todo list. If there is a corresponding ticket, feel free to specify its number in the comment. Unless other wise specified, issue #1234 means a ticket in the trac, available at http://kea.isc.org.
|
|
</details>
|
|
</details>
|
|
|
|
|
|
## Dead code
|
|
## Dead code
|
|
|
|
|
|
Dead code is bad; it suffers from code rot, and it looks unclean. There are some circumstances where there is a reason to keep a bit of unused code around for a while, but these should be the exception rather than the rule, and it should be very clear why it is there, and on what conditions and when it will be re-enabled or removed completely.
|
|
Dead code is bad; it suffers from code rot, and it looks unclean. There are some circumstances where there is a reason to keep a bit of unused code around for a while, but these should be the exception rather than the rule, and it should be very clear why it is there, and on what conditions and when it will be re-enabled or removed completely.
|
|
|
|
|
|
Any dead code (both files that are unused and blocks of commented-out code) should in principle be removed. If there is a very good reason to keep it around for a while, it must be accompanied by a comment explaining why it is still there, and when it will be removed or enabled again. This comment should point to a ticket so that we do not forget about it.
|
|
Any dead code (both files that are unused and blocks of commented-out code) should in principle be removed. If there is a very good reason to keep it around for a while, it must be accompanied by a comment explaining why it is still there, and when it will be removed or enabled again. This comment should point to a ticket so that we do not forget about it.
|
|
|
|
|
|
# Python Style
|
|
# Python Style
|
|
We don't use python code anymore in the core code. If you found any leftovers, feel free to remove them.
|
|
We don't use python code anymore in the core code. If you found any leftovers, feel free to remove them.
|
|
|
|
|
|
(note this can change with the RBAC reverse proxy prototype and anyway documentation is built using Sphinx so we have a lot of python code for not core critical code)
|
|
(note this can change with the RBAC reverse proxy prototype and anyway documentation is built using Sphinx so we have a lot of python code for not core critical code)
|
|
|
|
|
|
# C++ Style
|
|
# C++ Style
|
|
|
|
|
|
<details>
|
|
<details>
|
|
<summary> File Name Conventions </summary>
|
|
<summary> File Name Conventions </summary>
|
... | @@ -41,17 +41,17 @@ Use .cc for C++ source files. This is basically a mere preference and to ensure |
... | @@ -41,17 +41,17 @@ Use .cc for C++ source files. This is basically a mere preference and to ensure |
|
|
|
|
|
Use .h for C++ header files. This is because we may want to provide a C-callable wrapper for some APIs, and some C++ header files are to be included in a C source file. In that case C-compatible file names will look more natural.
|
|
Use .h for C++ header files. This is because we may want to provide a C-callable wrapper for some APIs, and some C++ header files are to be included in a C source file. In that case C-compatible file names will look more natural.
|
|
|
|
|
|
Use all all-lowercase characters for file names. This is consistent with the current recommendation for python, and so it will make the file name convention consistent throughout the BIND10 source tree. Not mixing lower/upper cases will also help avoid name conflicts in a case insensitive file system. Note that this policy may not compatible with C++ class name convention (see below) if the file name is based on the class name (e.g., name "myclass.cc" for the definition of the "Myclass" classs). We explicitly accept the conflict, but note that this means it will effectively prohibit mixing cases in class names ("Myclass" and "!MyClass" may not coexist).
|
|
Use all all-lowercase characters for file names. This is consistent with the current recommendation for python, and so it will make the file name convention consistent throughout the BIND10 source tree. Not mixing lower/upper cases will also help avoid name conflicts in a case insensitive file system. Note that this policy may not compatible with C++ class name convention (see below) if the file name is based on the class name (e.g., name "myclass.cc" for the definition of the "Myclass" class). We explicitly accept the conflict, but note that this means it will effectively prohibit mixing cases in class names ("Myclass" and "!MyClass" may not coexist).
|
|
|
|
|
|
Note header files should not include config.h.
|
|
Note header files should not include config.h.
|
|
</details>
|
|
</details>
|
|
|
|
|
|
## Ordering Include Files
|
|
## Ordering Include Files
|
|
|
|
|
|
We include our own project headers first, then library, and finally system headers, whenever possible. Each header is expected to have any necessary #include statements it needs, and this helps insure that.
|
|
We include our own project headers first, then library, and finally system headers, whenever possible. Each header is expected to have any necessary #include statements it needs, and this helps insure that.
|
|
|
|
|
|
```cpp
|
|
```cpp
|
|
#include <dns/message.h>
|
|
#include <dns/message.h>
|
|
#include <boost/shared_ptr.hpp>
|
|
#include <boost/shared_ptr.hpp>
|
|
#include <string>
|
|
#include <string>
|
|
```
|
|
```
|
... | @@ -61,7 +61,7 @@ particular header file must be included first. A notable example is |
... | @@ -61,7 +61,7 @@ particular header file must be included first. A notable example is |
|
Python.h. The top level config.h generated by autoconf should also be
|
|
Python.h. The top level config.h generated by autoconf should also be
|
|
included before other generic header files.
|
|
included before other generic header files.
|
|
|
|
|
|
## Include Style
|
|
## Include Style
|
|
|
|
|
|
We use the pointy brackets version of `#include`. Also, we use a full path to
|
|
We use the pointy brackets version of `#include`. Also, we use a full path to
|
|
the include (relative to some `-I` switch, not to the current directory).
|
|
the include (relative to some `-I` switch, not to the current directory).
|
... | @@ -78,18 +78,18 @@ Incorrect: |
... | @@ -78,18 +78,18 @@ Incorrect: |
|
#include "name.h"
|
|
#include "name.h"
|
|
```
|
|
```
|
|
|
|
|
|
## Line length
|
|
## Line length
|
|
|
|
|
|
Source code not exceeding 80 columns is preferred. This is derived from
|
|
Source code not exceeding 80 columns is preferred. This is derived from
|
|
the [wiki:BIND9CodingGuidelines BIND 9 coding guidelines], mainly for
|
|
the [wiki:BIND9CodingGuidelines BIND 9 coding guidelines], mainly for
|
|
style consistency. However, C++ names (especially with namespaces) are significantly
|
|
style consistency. However, C++ names (especially with namespaces) are significantly
|
|
longer, thus strictly adhering to this causes overly wrapped code that is both
|
|
longer, thus strictly adhering to this causes overly wrapped code that is both
|
|
ugly and difficult to read. Therefore it is permitted to use lines up to 100 columns long.
|
|
ugly and difficult to read. Therefore it is permitted to use lines up to 100 columns long.
|
|
|
|
|
|
Rationale: It is 2015 and all ISC employees have equipment that is at most 3 years old. You should have
|
|
Rationale: It is 2015 and all ISC employees have equipment that is at most 3 years old. You should have
|
|
FullHD (or better) display available to you. You should be able to display two files side by side comfortably.
|
|
FullHD (or better) display available to you. You should be able to display two files side by side comfortably.
|
|
|
|
|
|
## Tabs & Indentation
|
|
## Tabs & Indentation
|
|
|
|
|
|
Do not use hard tabs.
|
|
Do not use hard tabs.
|
|
|
|
|
... | @@ -104,7 +104,7 @@ if (JS_DefineProperty(cx, o, "data", |
... | @@ -104,7 +104,7 @@ if (JS_DefineProperty(cx, o, "data", |
|
```
|
|
```
|
|
|
|
|
|
|
|
|
|
## Curly Braces
|
|
## Curly Braces
|
|
|
|
|
|
Always add braces even for a single-line block:
|
|
Always add braces even for a single-line block:
|
|
```cpp
|
|
```cpp
|
... | @@ -117,7 +117,7 @@ if (something_holds) { |
... | @@ -117,7 +117,7 @@ if (something_holds) { |
|
}
|
|
}
|
|
```
|
|
```
|
|
|
|
|
|
### Opening Curly Braces for Functions
|
|
### Opening Curly Braces for Functions
|
|
|
|
|
|
The opening curly brace should occur on the same line as the argument list, unless the argument list is more than one line long.
|
|
The opening curly brace should occur on the same line as the argument list, unless the argument list is more than one line long.
|
|
|
|
|
... | @@ -137,14 +137,14 @@ g(int i, /* other args here */ |
... | @@ -137,14 +137,14 @@ g(int i, /* other args here */ |
|
|
|
|
|
This was derived from the BIND 9 coding guideline. It's known this style may look awkward (and even may look inconsistent) for some, but for the reason stated at the beginning we follow this style.
|
|
This was derived from the BIND 9 coding guideline. It's known this style may look awkward (and even may look inconsistent) for some, but for the reason stated at the beginning we follow this style.
|
|
|
|
|
|
### Curly Braces for Catch
|
|
### Curly Braces for Catch
|
|
|
|
|
|
A catch statement should have braces on a single line, like this:
|
|
A catch statement should have braces on a single line, like this:
|
|
```cpp
|
|
```cpp
|
|
.
|
|
.
|
|
.
|
|
|
|
.
|
|
.
|
|
} catch (const SomeException& ex) {
|
|
.
|
|
|
|
} catch (const SomeException& ex) {
|
|
.
|
|
.
|
|
.
|
|
.
|
|
.
|
|
.
|
... | @@ -152,7 +152,7 @@ A catch statement should have braces on a single line, like this: |
... | @@ -152,7 +152,7 @@ A catch statement should have braces on a single line, like this: |
|
|
|
|
|
Note if the ex parameter is not used it should be omitted. There are only two forms of catch clauses which make sense: a const reference and the ... catch all.
|
|
Note if the ex parameter is not used it should be omitted. There are only two forms of catch clauses which make sense: a const reference and the ... catch all.
|
|
|
|
|
|
## Parentheses
|
|
## Parentheses
|
|
|
|
|
|
Do put a space after 'return', and also parenthesize the return value.
|
|
Do put a space after 'return', and also parenthesize the return value.
|
|
|
|
|
... | @@ -163,7 +163,7 @@ Do put a space after 'return', and also parenthesize the return value. |
... | @@ -163,7 +163,7 @@ Do put a space after 'return', and also parenthesize the return value. |
|
|
|
|
|
This was derived from the BIND 9 coding guideline.
|
|
This was derived from the BIND 9 coding guideline.
|
|
|
|
|
|
## Operators
|
|
## Operators
|
|
|
|
|
|
Use operator methods in a readable way. In particular, use the
|
|
Use operator methods in a readable way. In particular, use the
|
|
following style with `operator==`:
|
|
following style with `operator==`:
|
... | @@ -191,7 +191,7 @@ cleanly written C++ code (compared to plain old C). |
... | @@ -191,7 +191,7 @@ cleanly written C++ code (compared to plain old C). |
|
See also developers' discussions at:
|
|
See also developers' discussions at:
|
|
https://lists.isc.org/pipermail/bind10-dev/2012-March/003266.html
|
|
https://lists.isc.org/pipermail/bind10-dev/2012-March/003266.html
|
|
|
|
|
|
### Increment and Decrement operators (++/--)
|
|
### Increment and Decrement operators (++/--)
|
|
|
|
|
|
Use the prefix form of increment/decrement operators by default:
|
|
Use the prefix form of increment/decrement operators by default:
|
|
|
|
|
... | @@ -245,7 +245,7 @@ public: |
... | @@ -245,7 +245,7 @@ public: |
|
}
|
|
}
|
|
```
|
|
```
|
|
|
|
|
|
## Explicit Constructors
|
|
## Explicit Constructors
|
|
|
|
|
|
By default C++ constructors with one argument are conversion functions. When they are not (which is the general case) they should be explicit as in:
|
|
By default C++ constructors with one argument are conversion functions. When they are not (which is the general case) they should be explicit as in:
|
|
```cpp
|
|
```cpp
|
... | @@ -256,7 +256,7 @@ public: |
... | @@ -256,7 +256,7 @@ public: |
|
}
|
|
}
|
|
```
|
|
```
|
|
|
|
|
|
## Class Attributes
|
|
## Class Attributes
|
|
|
|
|
|
Accessors for class attributes should be called '''`getXxx()`'''.
|
|
Accessors for class attributes should be called '''`getXxx()`'''.
|
|
|
|
|
... | @@ -264,13 +264,13 @@ Mutators for class attributes should be called '''`setXxx()`'''. |
... | @@ -264,13 +264,13 @@ Mutators for class attributes should be called '''`setXxx()`'''. |
|
|
|
|
|
(where xxx is the attribute)
|
|
(where xxx is the attribute)
|
|
|
|
|
|
## Non-copyable Classes
|
|
## Non-copyable Classes
|
|
|
|
|
|
If you want a class to be non-copyable (neither copy constructor nor assignment), inherit from boost::noncopyable rather than implementing this yourself.
|
|
If you want a class to be non-copyable (neither copy constructor nor assignment), inherit from boost::noncopyable rather than implementing this yourself.
|
|
|
|
|
|
http://www.boost.org/doc/libs/1_47_0/libs/utility/utility.htm#Class_noncopyable
|
|
http://www.boost.org/doc/libs/1_47_0/libs/utility/utility.htm#Class_noncopyable
|
|
|
|
|
|
## Naming
|
|
## Naming
|
|
|
|
|
|
Don't start things with underscores. According to Stroustrup's C++ book:
|
|
Don't start things with underscores. According to Stroustrup's C++ book:
|
|
Names starting with an underscore are reserved for special facilities in the implementation and the run-time environment, so such names should not be used in application programs.
|
|
Names starting with an underscore are reserved for special facilities in the implementation and the run-time environment, so such names should not be used in application programs.
|
... | @@ -307,7 +307,7 @@ int& int_ref; |
... | @@ -307,7 +307,7 @@ int& int_ref; |
|
The C++ standard does not require that `sizeof(bool)` is one: it is compiler dependent!
|
|
The C++ standard does not require that `sizeof(bool)` is one: it is compiler dependent!
|
|
So it should not be used and `sizeof(uint8_t)` is recommended instead.
|
|
So it should not be used and `sizeof(uint8_t)` is recommended instead.
|
|
|
|
|
|
## Comments
|
|
## Comments
|
|
|
|
|
|
Multiline comments can be written in C++ or C style (that is, with // or /* */ marks).
|
|
Multiline comments can be written in C++ or C style (that is, with // or /* */ marks).
|
|
|
|
|
... | @@ -337,7 +337,7 @@ class Foo { |
... | @@ -337,7 +337,7 @@ class Foo { |
|
};
|
|
};
|
|
```
|
|
```
|
|
|
|
|
|
### Doxygen Comment Style
|
|
### Doxygen Comment Style
|
|
|
|
|
|
When writing a Doxygen special comment block there are several possible styles:
|
|
When writing a Doxygen special comment block there are several possible styles:
|
|
|
|
|
... | @@ -380,13 +380,13 @@ class Good { |
... | @@ -380,13 +380,13 @@ class Good { |
|
|
|
|
|
|
|
|
|
|
|
|
|
### Explicit @brief for Doxygen
|
|
### 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.
|
|
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
|
|
## Methods and Functions
|
|
|
|
|
|
### Opening Curly Braces
|
|
### Opening Curly Braces
|
|
|
|
|
|
For methods where the arguments all fit on one line with the curly brace, it should be written on one line:
|
|
For methods where the arguments all fit on one line with the curly brace, it should be written on one line:
|
|
|
|
|
... | @@ -408,7 +408,7 @@ methodName(int argument_one, std::string message, |
... | @@ -408,7 +408,7 @@ methodName(int argument_one, std::string message, |
|
}
|
|
}
|
|
```
|
|
```
|
|
|
|
|
|
### Virtual Methods
|
|
### Virtual Methods
|
|
|
|
|
|
Explicitly add `virtual` to method declarations in derived classes:
|
|
Explicitly add `virtual` to method declarations in derived classes:
|
|
|
|
|
... | @@ -433,7 +433,7 @@ as a virtual methods for classes derived further from `Derived`, but |
... | @@ -433,7 +433,7 @@ as a virtual methods for classes derived further from `Derived`, but |
|
in practice that's a very rare case; in most cases we use these classes
|
|
in practice that's a very rare case; in most cases we use these classes
|
|
through the (top) base class interfaces.
|
|
through the (top) base class interfaces.
|
|
|
|
|
|
### Const references
|
|
### Const references
|
|
|
|
|
|
With anything but primitive types (like int or bare pointer), it is better to pass them as const reference when possible, to avoid overhead of calling the copy constructor and copying a lot of data.
|
|
With anything but primitive types (like int or bare pointer), it is better to pass them as const reference when possible, to avoid overhead of calling the copy constructor and copying a lot of data.
|
|
|
|
|
... | @@ -446,17 +446,17 @@ function(const boost::shared_ptr<DataType>& param) { |
... | @@ -446,17 +446,17 @@ function(const boost::shared_ptr<DataType>& param) { |
|
}
|
|
}
|
|
```
|
|
```
|
|
|
|
|
|
### Exception-safe getters and string-production methods
|
|
### 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.
|
|
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.
|
|
|
|
|
|
## Namespaces
|
|
## Namespaces
|
|
|
|
|
|
Namespaces will be lower case: '''isc::dns''', or '''isc::cc'''.
|
|
Namespaces will be lower case: '''isc::dns''', or '''isc::cc'''.
|
|
|
|
|
|
'''using namespace''' should never be used in a header file. They may be used in .cc source files.
|
|
'''using namespace''' should never be used in a header file. They may be used in .cc source files.
|
|
|
|
|
|
## Consts
|
|
## Consts
|
|
|
|
|
|
Use `const` as much as possible. Make class methods const member functions whenever possible.
|
|
Use `const` as much as possible. Make class methods const member functions whenever possible.
|
|
|
|
|
... | @@ -479,7 +479,7 @@ Technically, the latter `const` is redundant. But !SunStudio C++ compilers have |
... | @@ -479,7 +479,7 @@ Technically, the latter `const` is redundant. But !SunStudio C++ compilers have |
|
|
|
|
|
Unfortunately, we want to be as portable as possible, and so need to work around this by being redundant.
|
|
Unfortunately, we want to be as portable as possible, and so need to work around this by being redundant.
|
|
|
|
|
|
## NULL pointer check
|
|
## NULL pointer check
|
|
|
|
|
|
Use the "implicit" form when testing to see whether a pointer is 0
|
|
Use the "implicit" form when testing to see whether a pointer is 0
|
|
(`NULL`):
|
|
(`NULL`):
|
... | @@ -535,19 +535,19 @@ See also a mailing list discussion starting from: https://lists.isc.org/pipermai |
... | @@ -535,19 +535,19 @@ See also a mailing list discussion starting from: https://lists.isc.org/pipermai |
|
and related discussion in a conference call http://bind10.isc.org/wiki/WeeklyMinutes20130115
|
|
and related discussion in a conference call http://bind10.isc.org/wiki/WeeklyMinutes20130115
|
|
when we decided to make the change.
|
|
when we decided to make the change.
|
|
|
|
|
|
## Log Statement Safety
|
|
## Log Statement Safety
|
|
|
|
|
|
It is extremely important to examine all arguments passed into a log
|
|
It is extremely important to examine all arguments passed into a log
|
|
statement to ensure they will produce safe values at runtime:
|
|
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?
|
|
- Can the argument (or any part of it) be NULL? If so is this taken into account?
|
|
- If the argument invokes any fuctions, are they exception safe?
|
|
- If the argument invokes any functions, are they exception safe?
|
|
- If it involves indirection, does this always resolve into a usable value?
|
|
- 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.
|
|
- If it raises an exception, is the exception caught? This includes double errors, i.e., log statements in an exception handler.
|
|
- Does it have the intended data type? For example, it is a common oversight that 8-bit integers are displayed as their ASCII character counterpart. To solve this, prepending a unary plus is the recommended solution ([cppreference.com](https://en.cppreference.com/w/cpp/language/operator_arithmetic#Unary_arithmetic_operators): `1. unary plus (promotion). [...] Integral promotion is performed on the operand if it has integral or unscoped enumeration type and determines the type of the result.`).
|
|
- Does it have the intended data type? For example, it is a common oversight that 8-bit integers are displayed as their ASCII character counterpart. To solve this, prepending a unary plus is the recommended solution ([cppreference.com](https://en.cppreference.com/w/cpp/language/operator_arithmetic#Unary_arithmetic_operators): `1. unary plus (promotion). [...] Integral promotion is performed on the operand if it has integral or unscoped enumeration type and determines the type of the result.`).
|
|
|
|
|
|
Log statements are less than helpful if they cause the program to segfault or throw.
|
|
Log statements are less than helpful if they cause the program to segfault or throw.
|
|
|
|
|
|
## Google Test Style
|
|
## Google Test Style
|
|
|
|
|
|
Try to use EXPECT_<op>() rather than EXPECT_TRUE():
|
|
Try to use EXPECT_<op>() rather than EXPECT_TRUE():
|
|
|
|
|
... | @@ -564,20 +564,20 @@ Note that this is not always possible, especially when checking an |
... | @@ -564,20 +564,20 @@ Note that this is not always possible, especially when checking an |
|
object that has no operator<<() (or more obviously no operator<op>()),
|
|
object that has no operator<<() (or more obviously no operator<op>()),
|
|
which is used to output on failure.
|
|
which is used to output on failure.
|
|
|
|
|
|
## Test naming
|
|
## Test naming
|
|
|
|
|
|
Names of tests should be similar to classes and method names for that language. For example:
|
|
Names of tests should be similar to classes and method names for that language. For example:
|
|
|
|
|
|
* for gtest C++ tests, you'd use `CamelCaseTest` as the fixture class name, and `testName()` as the test name (as it is a C++ method).
|
|
* for gtest C++ tests, you'd use `CamelCaseTest` as the fixture class name, and `testName()` as the test name (as it is a C++ method).
|
|
* for Python unittests, you'd use `CamelCaseTest` as the fixture class name, and `test_something()` as the test name (as it is a Python method).
|
|
* for Python unittests, you'd use `CamelCaseTest` as the fixture class name, and `test_something()` as the test name (as it is a Python method).
|
|
|
|
|
|
# Makefile.am Guidelines
|
|
# Makefile.am Guidelines
|
|
|
|
|
|
## Make portability
|
|
## Make portability
|
|
|
|
|
|
Makefiles must never depend on a particular make, for instance the `$(<function> ...)` construct of GNU make for shell, foreach, wildcard, etc, are forbidden.
|
|
Makefiles must never depend on a particular make, for instance the `$(<function> ...)` construct of GNU make for shell, foreach, wildcard, etc, are forbidden.
|
|
|
|
|
|
## Subdirectories
|
|
## Subdirectories
|
|
|
|
|
|
If there is are one or more subdirectories, the first line in the file
|
|
If there is are one or more subdirectories, the first line in the file
|
|
should be the SUBDIRS entry, e.g.:
|
|
should be the SUBDIRS entry, e.g.:
|
... | @@ -588,7 +588,7 @@ SUBDIRS = . tests |
... | @@ -588,7 +588,7 @@ SUBDIRS = . tests |
|
If relevant (as is usually the case), the current directory should be
|
|
If relevant (as is usually the case), the current directory should be
|
|
included in the list at the appropriate point in the list.
|
|
included in the list at the appropriate point in the list.
|
|
|
|
|
|
## Preprocessor flags / includes
|
|
## Preprocessor flags / includes
|
|
|
|
|
|
Next should be the setting of the AM_CPPFLAGS, which applies to every
|
|
Next should be the setting of the AM_CPPFLAGS, which applies to every
|
|
module built with C++ in the Makefile.am, e.g.:
|
|
module built with C++ in the Makefile.am, e.g.:
|
... | @@ -597,7 +597,7 @@ AM_CPPFLAGS = -I$(top_srcdir)/src/lib -I$(top_builddir)/src/lib |
... | @@ -597,7 +597,7 @@ AM_CPPFLAGS = -I$(top_srcdir)/src/lib -I$(top_builddir)/src/lib |
|
AM_CPPFLAGS += $(BOOST_INCLUDES)
|
|
AM_CPPFLAGS += $(BOOST_INCLUDES)
|
|
```
|
|
```
|
|
|
|
|
|
This can be overriden on a per-module basis in the file by specifying
|
|
This can be overridden on a per-module basis in the file by specifying
|
|
the variable module_CPPFLAGS. (Note that if the CPPFLAGS environment
|
|
the variable module_CPPFLAGS. (Note that if the CPPFLAGS environment
|
|
variable is set, its flags are appended to the command line after
|
|
variable is set, its flags are appended to the command line after
|
|
AM_CPPFLAGS.)
|
|
AM_CPPFLAGS.)
|
... | @@ -613,7 +613,7 @@ AM_CXXFLAGS should be initialized to KEA_CXXFLAGS, e.g.: |
... | @@ -613,7 +613,7 @@ AM_CXXFLAGS should be initialized to KEA_CXXFLAGS, e.g.: |
|
AM_CXXFLAGS = $(KEA_CXXFLAGS)
|
|
AM_CXXFLAGS = $(KEA_CXXFLAGS)
|
|
```
|
|
```
|
|
|
|
|
|
## Linker flags
|
|
## Linker flags
|
|
|
|
|
|
When executables are build, AM_LDFLAGS must be conditionally set to static, e.g.:
|
|
When executables are build, AM_LDFLAGS must be conditionally set to static, e.g.:
|
|
```
|
|
```
|
... | @@ -622,7 +622,7 @@ AM_LDFLAGS = -static |
... | @@ -622,7 +622,7 @@ AM_LDFLAGS = -static |
|
endif
|
|
endif
|
|
```
|
|
```
|
|
|
|
|
|
## Library dependencies
|
|
## Library dependencies
|
|
|
|
|
|
With the exception of archives, (dynamic) libraries and executables should be linked
|
|
With the exception of archives, (dynamic) libraries and executables should be linked
|
|
with all dependencies in the opposite order of src/lib/Makefile.am for
|
|
with all dependencies in the opposite order of src/lib/Makefile.am for
|
... | @@ -637,11 +637,11 @@ If the libcfgrpt is used for embedding config_report it must be linked first, in |
... | @@ -637,11 +637,11 @@ If the libcfgrpt is used for embedding config_report it must be linked first, in |
|
if it is linked after libprocess some linkers can believe the config_report symbol is resolved
|
|
if it is linked after libprocess some linkers can believe the config_report symbol is resolved
|
|
by libprocess and does not include its static definition.
|
|
by libprocess and does not include its static definition.
|
|
|
|
|
|
# User Interface (UI) Guidelines
|
|
# User Interface (UI) Guidelines
|
|
|
|
|
|
Kea is a server process, so does not have much that would be considered a user interface. This section discusses what we do have. See [Stork coding guidelines](https://gitlab.isc.org/isc-projects/stork/-/wikis/Processes/coding-guidelines) for UI guidelines for Stork.
|
|
Kea is a server process, so does not have much that would be considered a user interface. This section discusses what we do have. See [Stork coding guidelines](https://gitlab.isc.org/isc-projects/stork/-/wikis/Processes/coding-guidelines) for UI guidelines for Stork.
|
|
|
|
|
|
## IP address and port formatting
|
|
## IP address and port formatting
|
|
|
|
|
|
Whenever an IP address and port is output, IETF RFC 2396 and RFC 2732 should be followed.
|
|
Whenever an IP address and port is output, IETF RFC 2396 and RFC 2732 should be followed.
|
|
|
|
|
... | @@ -653,18 +653,18 @@ For IPv6 addresses, this looks like this: |
... | @@ -653,18 +653,18 @@ For IPv6 addresses, this looks like this: |
|
|
|
|
|
[2001:db8::1]:53
|
|
[2001:db8::1]:53
|
|
|
|
|
|
# Imported Code
|
|
# 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.
|
|
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.
|
|
|
|
|
|
# Deprecating options
|
|
# Deprecating options
|
|
|
|
|
|
Sometimes we need to introduce changes that are not backward compatible. If possible we try to support the old way while making the new way possible. When introducing new alternative ("new way") that eventually going to replace an existing option ("old way"), there should be at least one stable series which supports both old and new way. If old syntax is used, a warning should be printed urging people to update their syntax.
|
|
Sometimes we need to introduce changes that are not backward compatible. If possible we try to support the old way while making the new way possible. When introducing new alternative ("new way") that eventually going to replace an existing option ("old way"), there should be at least one stable series which supports both old and new way. If old syntax is used, a warning should be printed urging people to update their syntax.
|
|
|
|
|
|
For example:
|
|
For example:
|
|
The old `reservation-mode` parameter has been replaced with `reservations-global`, `reservations-in-subnet` and `reservations-out-of-pool` in 1.9.2. A warning should be printed if `reservation-mode` is used. Such a warning should be coded as soon as realistically possible to give people as much advance warning as possible. As such, this will be implemented in 1.9.2, so early adopters will see it right way. It will be included in 2.0, where users preferring stable will see it. The old way can be removed somewhere in 2.1.x, so 2.2 will not accept it anymore. This way people who use only stable version will have time to migrate. They'll see the warning when moving from 1.8 to 2.0 and will have time until 2.2.
|
|
The old `reservation-mode` parameter has been replaced with `reservations-global`, `reservations-in-subnet` and `reservations-out-of-pool` in 1.9.2. A warning should be printed if `reservation-mode` is used. Such a warning should be coded as soon as realistically possible to give people as much advance warning as possible. As such, this will be implemented in 1.9.2, so early adopters will see it right way. It will be included in 2.0, where users preferring stable will see it. The old way can be removed somewhere in 2.1.x, so 2.2 will not accept it anymore. This way people who use only stable version will have time to migrate. They'll see the warning when moving from 1.8 to 2.0 and will have time until 2.2.
|
|
|
|
|
|
# Guidelines Adopted by Other Projects
|
|
# Guidelines Adopted by Other Projects
|
|
|
|
|
|
Other projects have their own coding guidelines. Here're some
|
|
Other projects have their own coding guidelines. Here're some
|
|
examples of such guidelines. These are reference purposes only;
|
|
examples of such guidelines. These are reference purposes only;
|
... | @@ -674,4 +674,3 @@ they are not part of the BIND 10's coding guidelines. |
... | @@ -674,4 +674,3 @@ they are not part of the BIND 10's coding guidelines. |
|
* Google: http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml
|
|
* Google: http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml
|
|
* Mozilla: https://developer.mozilla.org/en/Mozilla_Coding_Style_Guide
|
|
* Mozilla: https://developer.mozilla.org/en/Mozilla_Coding_Style_Guide
|
|
* XORP: http://cvsweb.xorp.org/cgi-bin/cvsweb.cgi/xorp/devnotes/coding-style.txt?rev=1.7;content-type=text%2Fplain |
|
* XORP: http://cvsweb.xorp.org/cgi-bin/cvsweb.cgi/xorp/devnotes/coding-style.txt?rev=1.7;content-type=text%2Fplain |
|
|
|
|