Add documentation for using assertions.

source/doc/coding_rules/src/opener_coding_rules.tex

@@ -246,4 +246,64 @@ \section{Code Formatting}
 In order to have consistent code formating the Google C++ coding style rules shall apply. When using Eclipse as development environment the coding format xml file is available at \url{https://github.com/google/styleguide}. By pressing \verb|<ctrl><shift>f| the formatter will format the code according to these rules.
 
 
-\end{document}
+\section{Assertions}
+The \lstinline!OPENER_ASSERT(e)! macro is available for traditional
+assertion checks, halting the program if the expression provided as the
+argument \lstinline!e! evaluates false. This macro shall \emph{only} be used
+to test conditions where the only possible cause of failure is an
+unquestionable bug with this program, typically leading to undefined behavior
+or a crash if execution were permitted to continue.
+In other words, an assertion shall \emph{never} fail
+as a result of any external input, valid or invalid,
+or other similar foreseeable condition, such as a memory allocation failure.
+These latter type of failures must be handled by normal code execution paths
+that yield responses with appropriate error codes or possibly
+terminating the program with a non-zero exit code, not an assertion failure.
+
+The following listing of a function to set an attribute's value based
+on received data is an example to help illustrate proper use of assertions.
+The \lstinline!raw! and \lstinline!len! parameters
+refer to the received data and length, and the \lstinline!foo! parameter
+points to the target attribute; the function returns true only if the attribute
+was set successfully.
+
+\begin{quote}
+\begin{lstlisting}
+ bool SetAttributeFoo(const void *raw, size_t len, CipDint *foo) {
+
+ /*
+ * This function should never be called with NULL pointers, regardless of
+ * what was received over the network, so assertions should be used to
+ * validate the pointer arguments.
+ */
+ OPENER_ASSERT(NULL != raw);
+ OPENER_ASSERT(NULL != foo);
+
+ /*
+ * Ensuring enough data was received to satisfy the target data type
+ * must not be done with an assertion as a malformed message containing
+ * insufficient data shall not halt the program.
+ */
+ if (sizeof(CipDint) > len) {
+ return false;
+ }
+
+ CipDint new_value = &(int *)raw;
+
+ /*
+ * Here the received value is tested for conformance to acceptable values;
+ * assume for the sake of this example that allowable values are nonzero.
+ * Validating values received from external sources must not be done
+ * with assertions.
+ */
+ if (0 == new_value) {
+ return false;
+ }
+
+ *foo = new_value;
+ return true;
+ }
+\end{lstlisting}
+\end{quote}
+
+\end{document}