From 41e0e56091413426ace0cab73266806a0b43b287 Mon Sep 17 00:00:00 2001 From: Denis Davydov Date: Thu, 27 Oct 2016 17:10:22 +0200 Subject: [PATCH] document coding conventions for templates --- doc/doxygen/headers/coding_conventions.h | 41 ++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/doc/doxygen/headers/coding_conventions.h b/doc/doxygen/headers/coding_conventions.h index 02ab55bf35..6d3bf13bf7 100644 --- a/doc/doxygen/headers/coding_conventions.h +++ b/doc/doxygen/headers/coding_conventions.h @@ -161,6 +161,47 @@ source files. +

Instantiation of templated functions/classes

+ +

Majority of classes and functions in deal.II are templated. This brings a +question of how and where such objects are instantiated, if at all. Throughout +deal.II we adopt the following convention:

+ +
    + +
  1. If we can enumerate all possible template arguments (e.g., the dimension +can only be 1, 2, or 3), then a function template goes into the .cc file and +we explicitly instantiate all possibilities. Users will not have any need to +ever see these function templates because they will not want to instantiate +these functions for any other template arguments anyway.
  2. + +
  3. If we can not enumerate all possible template arguments (e.g., vector +types -- because users might want to define their own vector kinds) but at +least know a few common usage cases, then the function is put into a +.templates.h file. We #include it into the .cc file and instantiate the +functions for all of the common arguments. For almost all users, this will be +just fine -- they only use the (vector, matrix, ...) types we already +instantiate, and for them the .templates.h file will not be of any interest. +It will also not slow down their compilations because nothing they see will +#include the .templates.h file. But users who define their own +(vector, matrix, ...) types can instantiate the template functions with their +own user-defined types by #includeing the .templates.h files. + +
  4. Finally, if we can not assume in advance which values template arguments +will take (e.g., any class derived from Subscriptor can be used as an argument), +the definitions of functions are provided at the bottom of the header +file with declarations. The definitions should be guarded with #ifndef DOXYGEN ... +#endif to prevent Doxygen from picking them up.
  5. + +
+ +

For the first two cases, instantiation instructions are defined in .inst.in +files. These files are processed by custom CMake scripts to generate .inst files +using lists of parameters (vector classes, dimensions, tensor ranks, etc) +defined in cmake/config/template-arguments.in. It is those .inst +files that are eventually included from the corresponding .cc files.

+ +

Defensive programming

Defensive programming is a term that we use frequently when we talk about -- 2.39.5