From: David Wells
Date: Fri, 11 Mar 2016 03:15:51 +0000 (-0500)
Subject: Describe forward declarations in the style guide.
X-Git-Tag: v8.5.0-rc1~1229^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F2332%2Fhead;p=dealii.git
Describe forward declarations in the style guide.
---
diff --git a/doc/doxygen/headers/coding_conventions.h b/doc/doxygen/headers/coding_conventions.h
index cf8d091f3c..b816f84d1d 100644
--- a/doc/doxygen/headers/coding_conventions.h
+++ b/doc/doxygen/headers/coding_conventions.h
@@ -134,6 +134,19 @@ style guidelines outlined in this page.
put before the data type specifier, i.e., we use Point and not
Point.
+ There are several places in deal.II where we use forward declarations in
+ header files. The reason for this is that we can, hopefully, improve
+ compilation speeds by not using headers when we just need to mark a certain
+ type as an argument to a function. The convention used in deal.II is that, if
+ all we need is a type name, then the type may be forward declared in the
+ header where we need it; if a function (or member function) can return a value
+ then a declaration of that value's type should be available (by including the
+ necessary header). For example, deal.II/dofs/dof_handler.h
+ includes deal.II/dofs/dof_accessor.h
so that one can write
+ something like dof_handler.begin_active()->is_active()
without
+ explicitly including the header declaring the type of the object returned by
+ begin_active()
.
+
Each class has to have at least 200 pages of documentation ;-)