|
This page documents some Stork coding guidelines.
|
|
This page documents some Stork coding guidelines.
|
|
|
|
|
|
|
|
**The update of this document is in progress...**
|
|
|
|
|
|
[[_TOC_]]
|
|
[[_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.
|
... | @@ -7,11 +9,13 @@ Some of the styles derived from BIND 9 that are often forgotten or misunderstood |
... | @@ -7,11 +9,13 @@ Some of the styles derived from BIND 9 that are often forgotten or misunderstood |
|
|
|
|
|
# Test-Driven Development
|
|
# Test-Driven Development
|
|
|
|
|
|
[Kea project](https://gitlab.isc.org/isc-projects/kea) proved beyond any doubt that [TDD](https://en.wikipedia.org/wiki/Test-driven_development) works and improves the code quality. We absolutely want to repeat the exercise in Stork. However, there are some lessons learned in Kea project. In general, unit-tests should be developed alongside the production code (before the code if possible) and included in the same MRs. Having said that, Kea project sometimes went a bit overboard with this and there were cases when people were wasting time implementing unit-tests for trivial getters and setters. That's not the goal here.
|
|
We use [test-driven development](https://en.wikipedia.org/wiki/Test-driven_development) in the Stork project. We require writing unit tests together with the code. The developers should write the unit tests before the implementation and make sure the tests initially fail. Implementing the code should cause these tests to pass. Creation of the tests after the implementation poses a risk that the tests do not correctly validate the implementation and pass regardless.
|
|
|
|
|
|
|
|
The unit tests should cover all functions, and our linters report errors when they detect missing coverage. However, it is essential to focus on testing all cases of complex functions rather than writing many tests for trivial functions.
|
|
|
|
|
|
The intention is to make sure that the most complex or tricky parts of the code should be testable and we should have reasonable confidence in them being correct. There's another essential aspect here. If you feel that it's not possible to write unit-tests for your new code, perhaps your new code is structured badly? This is one of two major reasons why the tests cannot be written letter. The other is that there's never good time to come back and implement tests...
|
|
There are cases when it is hard to write tests for some functions. For example, writing a unit test for a main() function may be hard. In legitimate cases, it is ok not to write a unit test for a function, and it should be decided on a case-by-case basis. Such cases should be covered in the system tests instead.
|
|
|
|
|
|
Finally, Stork is currently approved for 6 months. We don't want to have few features with super extensive tests. This could kill the project if the only thing we can show after 6 months is well written tests. On the other hand, we don't want to have tons of buggy features that don't work. We need to take a middle ground. Please use common sense. If in doubt, please ask @tomek for suggestions.
|
|
If writing a unit test for some code is hard or impossible, a developer should consider restructuring the code to allow testing.
|
|
|
|
|
|
# Documentation
|
|
# Documentation
|
|
|
|
|
... | | ... | |