2.4 KiB
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_argnoth argument (counting from 1)
and the variadic arguments start with the variadic_argnoth.
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 enabledH5_ATTR_NDEBUG_UNUSED: used only ifNDEBUGis not #definedH5_ATTR_DEBUG_API_USED: used if the debug API is enabledH5_ATTR_PARALLEL_UNUSED: used only if Parallel HDF5 is not configuredH5_ATTR_PARALLEL_USED: used only if Parallel HDF5 is configured
Some attributes may be phased in or phased out in the future.