diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index eed0d6b..e7301f8 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -4,7 +4,7 @@ If you are planning to add a new module (data structure or algorithm), you may w If you are planning to submit a pull request, please ensure that your change: * Is written in the C programming language. -* Conforms to the project's style guidelines. +* 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. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index cdadc0d..8dc59d2 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -7,7 +7,7 @@ If you are planning to add a new module (data structure or algorithm), you may w Before filing your pull request, please ensure that your change: * Is written in the C programming language. -* Conforms to the project's style guidelines. +* 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. diff --git a/Makefile.am b/Makefile.am index eaee2c2..5348827 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,7 +1,7 @@ AUX_DIST_GEN = $(ac_aux_dir) -EXTRA_DIST = $(AUX_DIST_GEN) libcalg-1.0.pc.in +EXTRA_DIST = $(AUX_DIST_GEN) libcalg-1.0.pc.in STYLE.md MAINTAINERCLEANFILES = $(AUX_DIST_GEN) pkgconfigdir = $(libdir)/pkgconfig diff --git a/STYLE.md b/STYLE.md new file mode 100644 index 0000000..60d4a71 --- /dev/null +++ b/STYLE.md @@ -0,0 +1,68 @@ + +The following are coding style guidelines for this project. + +Code is expected to be ANSI C compatible (C89). Use `/* ... */` comments, not +`// ...` comments. + +The style is a variant on the K&R style. + +To automatically format all source code, install +[clang-format](https://clang.llvm.org/docs/ClangFormat.html) and +run `make format`. + +## Blocks + +Tabs are used for indentation, spaces for alignment, eg. +```c +for (...) { +------>|function_call(..., ..., +------>| .....); +} +``` +Braces belong on the end of lines, eg. +```c +while (...) { + if (...) { + ... + } else { + ... + } +} +``` +The one exception is functions, where the brace goes on the next line: +```c +void foo(...) +{ + ... +} +``` + +## Naming + +Types are named with [camel case](https://en.wikipedia.org/wiki/Camel_case), +eg. `HashTable`. +All others (functions, variables, struct fields, etc.) are named with [snake +case](https://en.wikipedia.org/wiki/Snake_case), eg. `hash_table_new`. + +## Testing + +No code will be accepted without unit tests. See the [test](test/) directory +for what these should look like. Run `make check` to invoke the unit tests. + +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 + +All public interfaces must be documented using +[Doxygen](https://www.doxygen.nl/). For example: +```c +/** + * Retrieve the number of entries in a hash table. + * + * @param hash_table The hash table. + * @return The number of entries in the hash table. + */ +unsigned int hash_table_num_entries(HashTable *hash_table); +```