|
This page documents some Stork coding guidelines.
|
|
This page documents some Stork coding guidelines.
|
|
|
|
|
|
|
|
[[_TOC_]]
|
|
|
|
|
|
Refer also to the [Kea coding guidelines](https://gitlab.isc.org/isc-projects/kea/wikis/Processes/coding-guidelines) and [BIND best practices](https://gitlab.isc.org/isc-projects/bind9/wikis/best-practices). They should be used where they do not conflict with the guidelines on this page. This is because we expect some ISC developers work on both versions of code, and in that case it's easier to maintain the code if the styles are as compatible as possible.
|
|
Refer also to the [Kea coding guidelines](https://gitlab.isc.org/isc-projects/kea/wikis/Processes/coding-guidelines) and [BIND best practices](https://gitlab.isc.org/isc-projects/bind9/wikis/best-practices). They should be used where they do not conflict with the guidelines on this page. This is because we expect some ISC developers work on both versions of code, and in that case it's easier to maintain the code if the styles are as compatible as possible.
|
|
Some of the styles derived from BIND 9 that are often forgotten or misunderstood are explicitly mentioned below. Having said that, Stork is a project with radically different environment. We don't need to stick to old rules invented for C code in the 1990s.
|
|
Some of the styles derived from BIND 9 that are often forgotten or misunderstood are explicitly mentioned below. Having said that, Stork is a project with radically different environment. We don't need to stick to old rules invented for C code in the 1990s.
|
|
|
|
|
... | @@ -13,31 +15,23 @@ Finally, Stork is currently approved for 6 months. We don't want to have few fea |
... | @@ -13,31 +15,23 @@ Finally, Stork is currently approved for 6 months. We don't want to have few fea |
|
|
|
|
|
# Documentation
|
|
# Documentation
|
|
|
|
|
|
<details>
|
|
## Testing/Documentation addresses and prefixes
|
|
<summary>Testing/Documentation addresses and prefixes</summary>
|
|
|
|
|
|
|
|
Use 192.0.2.0/24 (see [RFC5737](https://tools.ietf.org/html/rfc5737) and 2001:db8::/32 (see [RFC3849](https://tools.ietf.org/html/rfc3849) for purposes like addresses used in test cases or examples in documentation. Likewise, use reserved example domain names such as example.com, .test, .example, etc for domain names used in these cases (see [RFC2606](https://tools.ietf.org/html/rfc2606)). They are reserved by specifications and should be the safest in terms of collision avoidance.
|
|
Use 192.0.2.0/24 (see [RFC5737](https://tools.ietf.org/html/rfc5737) and 2001:db8::/32 (see [RFC3849](https://tools.ietf.org/html/rfc3849) for purposes like addresses used in test cases or examples in documentation. Likewise, use reserved example domain names such as example.com, .test, .example, etc for domain names used in these cases (see [RFC2606](https://tools.ietf.org/html/rfc2606)). They are reserved by specifications and should be the safest in terms of collision avoidance.
|
|
|
|
|
|
</details>
|
|
## TODO Comments
|
|
<details>
|
|
|
|
<summary> TODO Comments </summary>
|
|
|
|
|
|
|
|
We sprinkle comments in code with keywords to indicate pending work.
|
|
We sprinkle comments in code with keywords to indicate pending work.
|
|
|
|
|
|
In Stork, @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 Gilab, available at http://gitlab.isc.org/isc-projects/stork.
|
|
In Stork, `TODO` is preferred. 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 Gilab, available at http://gitlab.isc.org/isc-projects/stork.
|
|
</details>
|
|
|
|
|
|
|
|
<details>
|
|
## Function/method comments
|
|
<summary>Function/method comments</summary>
|
|
|
|
Every non-trivial (trivial means one or two liner, such as getter or setter) function and method MUST be documented. While it's appreciated, the documentation doesn't have to be very thorough. Well expressed sentence is often enough. Make sure the description is as useful as possible. "Returns URL string" is bad. "Returns agent's contact point URL as a string" is much better.
|
|
Every non-trivial (trivial means one or two liner, such as getter or setter) function and method MUST be documented. While it's appreciated, the documentation doesn't have to be very thorough. Well expressed sentence is often enough. Make sure the description is as useful as possible. "Returns URL string" is bad. "Returns agent's contact point URL as a string" is much better.
|
|
</details>
|
|
|
|
|
|
|
|
<details>
|
|
## User's guide
|
|
<summary>User's guide</summary>
|
|
|
|
The User's guide should be updated when a new feature is added. Again, the description doesn't have to be complex or extensive. A paragraph of text briefly announcing new feature or capability will help users (and other developers) a lot.
|
|
The User's guide should be updated when a new feature is added. Again, the description doesn't have to be complex or extensive. A paragraph of text briefly announcing new feature or capability will help users (and other developers) a lot.
|
|
</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.
|
|
|
|
|
... | | ... | |