summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorDana Robinson <43805+derobins@users.noreply.github.com>2020-11-17 13:47:52 (GMT)
committerGitHub <noreply@github.com>2020-11-17 13:47:52 (GMT)
commit5d0be1b196570ac2c08ffe0b61ac6a45b6ab7f3f (patch)
treedbe8a76bcb211babe9900647eb1f515d8623ad9b /doc
parentec48fb8dfdb4f2f59f22a5efb6b950aafcac449d (diff)
downloadhdf5-5d0be1b196570ac2c08ffe0b61ac6a45b6ab7f3f.zip
hdf5-5d0be1b196570ac2c08ffe0b61ac6a45b6ab7f3f.tar.gz
hdf5-5d0be1b196570ac2c08ffe0b61ac6a45b6ab7f3f.tar.bz2
Manual sync with develop (#95)
Brings all features from develop. Note that RELEASE.txt has not been updated (will be done in a future PR).
Diffstat (limited to 'doc')
-rw-r--r--doc/code-conventions.md57
1 files changed, 57 insertions, 0 deletions
diff --git a/doc/code-conventions.md b/doc/code-conventions.md
new file mode 100644
index 0000000..ff3b4cf
--- /dev/null
+++ b/doc/code-conventions.md
@@ -0,0 +1,57 @@
+# HDF5 Library Code Conventions
+
+This document describes some practices that are new, or newly
+documented, starting in 2020.
+
+## Function / Variable Attributes
+
+In H5private.h, the library provides platform-independent macros
+for qualifying function and variable definitions.
+
+### Functions that accept `printf(3)` and `scanf(3)` format strings
+
+Label functions that accept a `printf(3)`-compliant format string with
+`H5_ATTR_FORMAT(printf,format_argno,variadic_argno)`, where
+the format string is the `format_argno`th argument (counting from 1)
+and the variadic arguments start with the `variadic_argno`th.
+
+Functions that accept a `scanf(3)`-compliant format string should
+be labeled `H5_ATTR_FORMAT(scanf,format_argno,variadic_argno)`.
+
+### Functions that do never return
+
+The definition of a function that always causes the program to abort and hang
+should be labeled `H5_ATTR_NORETURN` to help the compiler see which flows of
+control are infeasible.
+
+### Other attributes
+
+**TBD**
+
+### Unused variables and parameters
+
+Compilers will warn about unused parameters and variables—developers should pay
+attention to those warnings and make an effort to prevent them.
+
+Some function parameters and variables are unused in *all* configurations of
+the project. Ordinarily, such parameters and variables should be deleted.
+However, sometimes it is possible to foresee a parameter being used, or
+removing it would change an API, or a parameter has to be defined to conform a
+function to some function pointer type. In those cases, it's permissible to
+mark a symbol `H5_ATTR_UNUSED`.
+
+Other parameters and variables are unused in *some* configurations of the
+project, but not all. A symbol may fall into disuse in some configuration in
+the future—then the compiler should warn, and the symbol should not be
+defined—so developers should try to label a sometimes-unused symbol with an
+attribute that's specific to the configurations where the symbol is (or is not)
+expected to be used. The library provides the following attributes for that
+purpose:
+
+* `H5_ATTR_DEPRECATED_USED`: used only if deprecated symbols are enabled
+* `H5_ATTR_NDEBUG_UNUSED`: used only if `NDEBUG` is *not* \#defined
+* `H5_ATTR_DEBUG_API_USED`: used if the debug API is enabled
+* `H5_ATTR_PARALLEL_UNUSED`: used only if Parallel HDF5 *is not* configured
+* `H5_ATTR_PARALLEL_USED`: used only if Parallel HDF5 *is* configured
+
+Some attributes may be phased in or phased out in the future.