mirror of
https://github.com/HDFGroup/hdf5.git
synced 2024-12-03 02:32:04 +08:00
58 lines
2.4 KiB
Markdown
58 lines
2.4 KiB
Markdown
|
# 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.
|