diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 1124e6d..2a9e818 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -2,12 +2,13 @@ This project is intended to contain high quality implementations of data structu If you are planning to add a new module (data structure or algorithm), you may want to open an issue to discuss your plan with the project maintainer first. This will avoid wasted effort on your part. -If you are planning to submit a pull request, please ensure that your change: +If you are planning to submit a pull request, please ensure that your code: * Is written in the C programming language. * Conforms to the project's [style guidelines](../STYLE.md). * Does not duplicate existing code already present. * Passes all unit test checks (existing code). Run `make check` to confirm. * Adds unit tests (new code) with at least 95% coverage. Build with `configure –enable-coverage` to confirm. +* Is appropriately commented using full English sentences. * Is properly documented using Doxygen comments. Automated continuous integration checks will fail for many of the above requirements if they are not satisfied. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index b19688e..ae67cbe 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -5,13 +5,14 @@ This project is intended to contain high quality implementations of data structu If you are planning to add a new module (data structure or algorithm), you may want to open an issue to discuss your plan with the project maintainer first. This will avoid wasted effort on your part. -Before filing your pull request, please ensure that your change: +Before filing your pull request, please ensure that your code: * Is written in the C programming language. * Conforms to the project's style guidelines (see STYLE.md). * Does not duplicate existing code already present. * Passes all unit test checks (existing code). Run `make check` to confirm. * Adds unit tests (new code) with at least 95% coverage. Build with `configure –enable-coverage` to confirm. +* Is appropriately commented using full English sentences. * Is properly documented using Doxygen comments. Automated continuous integration checks will fail for many of the above requirements if they are not satisfied. -→ +--> diff --git a/STYLE.md b/STYLE.md index 524aa6e..cfd0fe3 100644 --- a/STYLE.md +++ b/STYLE.md @@ -59,8 +59,23 @@ Tests should [cover](https://en.wikipedia.org/wiki/Code_coverage) at least 95% of lines. Configure the project using `./configure --enable-coverage` and then run `make check`. -## Documentation +## Comments +Code should be commented using full English sentences. In general, try not to +document "what" the code is doing, but rather the "how" and "why". Most people, +for example, would agree that the following is an example of a comment that is +not useful: +```c + /* Free the node */ + free(node); +``` +The following is a comment that is more enlightening to the reader: +```c + /* The node to be removed must be swapped with an "adjacent" + * node, ie. one which has the closest key to this one. Find + * a node to swap with. */ + swap_node = avl_tree_node_get_replacement(tree, node); +``` All public interfaces must be documented using [Doxygen](https://www.doxygen.nl/). For example: ```c