mirror of
https://github.com/HDFGroup/hdf5.git
synced 2026-10-03 04:03:27 +03:00
59 lines
2.8 KiB
Plaintext
59 lines
2.8 KiB
Plaintext
/** \page CODECONV HDF5 Library Code Conventions
|
|
|
|
This document describes some practices that are new, or newly
|
|
documented, starting in 2020.
|
|
|
|
\section sec_codeconv_func Function / Variable Attributes
|
|
|
|
In H5private.h, the library provides platform-independent macros
|
|
for qualifying function and variable definitions.
|
|
|
|
\subsection subsec_codeconv_func_1 Functions that accept <code>printf(3)</code> and <code>scanf(3)</code> format strings
|
|
|
|
Label functions that accept a <code>printf(3)</code>-compliant format string with
|
|
<code>H5_ATTR_FORMAT(printf,format_argno,variadic_argno)</code>, where
|
|
the format string is the <code>format_argno</code>th argument (counting from 1)
|
|
and the variadic arguments start with the <code>variadic_argno</code>th.
|
|
|
|
Functions that accept a <code>scanf(3)</code>-compliant format string should
|
|
be labeled <code>H5_ATTR_FORMAT(scanf,format_argno,variadic_argno)</code>.
|
|
|
|
\subsection subsec_codeconv_func_2 Functions that do never return
|
|
|
|
The definition of a function that always causes the program to abort and hang
|
|
should be labeled <code>H5_ATTR_NORETURN</code> to help the compiler see which flows of
|
|
control are infeasible.
|
|
|
|
\subsection subsec_codeconv_func_other Other attributes
|
|
|
|
**TBD**
|
|
|
|
\subsection subsec_codeconv_func_unused 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 \b 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 <code>H5_ATTR_UNUSED</code>.
|
|
|
|
Other parameters and variables are unused in \b 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:
|
|
\li <code>H5_ATTR_DEPRECATED_USED</code>: used only if deprecated symbols \b are enabled
|
|
\li <code>H5_ATTR_NDEBUG_UNUSED</code>: used only if <code>NDEBUG</code> is \b not \#defined
|
|
\li <code>H5_ATTR_DEBUG_API_USED</code>: used if the debug API \b is enabled
|
|
\li <code>H5_ATTR_PARALLEL_UNUSED</code>: used only if Parallel HDF5 is \b not configured
|
|
\li <code>H5_ATTR_PARALLEL_USED</code>: used only if Parallel HDF5 \b is configured
|
|
|
|
Some attributes may be phased in or phased out in the future.
|
|
|
|
*/
|