/** \page CODECONV HDF5 Library Code Conventions

Navigate back: \ref index "Main" / \ref TN
<hr>

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.

<hr>
Navigate back: \ref index "Main" / \ref TN

*/