Add point about commenting

Author: fragglet

.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.

.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.
-→
+-->

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