diff options
| author | Larry Knox <lrknox@hdfgroup.org> | 2021-07-06 18:21:42 (GMT) |
|---|---|---|
| committer | Larry Knox <lrknox@hdfgroup.org> | 2021-07-06 18:21:42 (GMT) |
| commit | 820695a78e3a277daea1bdcbb8ad54b8ee6650a5 (patch) | |
| tree | fe7545305c0a77db3b9671e5a82fdffc4b2cc82e /doc/code-conventions.md | |
| parent | 9f13ecfa2e93840d1cc45dbf0bfcf8b955814931 (diff) | |
| parent | 18bbd3f0a7f14adeebf8f342ed242ff191f9b7c5 (diff) | |
| download | hdf5-hdf5-1_12_1.zip hdf5-hdf5-1_12_1.tar.gz hdf5-hdf5-1_12_1.tar.bz2 | |
Merge remote-tracking branch 'origin/hdf5_1_12_1' into 1.12/master forhdf5-1_12_1
HDF5 1.12.1 release.
Diffstat (limited to 'doc/code-conventions.md')
| -rw-r--r-- | doc/code-conventions.md | 57 |
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. |