... | @@ -30,10 +30,34 @@ We sprinkle comments in code with keywords to indicate pending work. |
... | @@ -30,10 +30,34 @@ We sprinkle comments in code with keywords to indicate pending work. |
|
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 Gitlab, 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 Gitlab, available at http://gitlab.isc.org/isc-projects/stork.
|
|
|
|
|
|
## Function/method comments
|
|
## Function/method comments
|
|
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.
|
|
|
|
|
|
### Golang
|
|
|
|
|
|
|
|
All exported functions MUST be documented. It is strongly recommended to document unexported functions, too, unless the function is trivial and its behavior is obvious without such documentation.
|
|
|
|
|
|
|
|
Always describe what the function is doing. If the function has a small number of parameters, and their purpose stems from the function description, there is no need to describe the parameters. However, complex functions with many parameters SHOULD include parameters descriptions highlighting their purpose, if they are mandatory, allowed ranges, and other helpful information.
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
A Golang function can return multiple values, named or unnamed. Providing additional documentation of the returned values is unnecessary when the function returns named parameters and their purpose is obvious from their names and function description.
|
|
|
|
|
|
|
|
If a function returns a single value and an error and the purpose of the returned value is obvious from the function description, there is no need to document the returned values. For example:
|
|
|
|
|
|
|
|
```golang
|
|
|
|
func GetSubnets() ([]Subnet, error)
|
|
|
|
```
|
|
|
|
|
|
|
|
In other cases, the returned values MUST be documented. For example, consider the following function signature:
|
|
|
|
|
|
|
|
```
|
|
|
|
func GetStats() (int64, int64)
|
|
|
|
```
|
|
|
|
|
|
|
|
Such a function must contain the description of the returned values. Otherwise, there is no way to tell what it returns, in what order, and what are the expected ranges of these values.
|
|
|
|
|
|
## User's guide
|
|
## User's guide
|
|
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 [Stork ARM](https://stork.readthedocs.io/en/latest/) 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.
|
|
|
|
|
|
# Dead code
|
|
# Dead code
|
|
|
|
|
... | | ... | |