From e37ba9582d81b9341ceef3ff3f6ef03f6095e011 Mon Sep 17 00:00:00 2001
From: David Wells
Date: Thu, 10 Mar 2016 22:15:51 -0500
Subject: [PATCH] Describe forward declarations in the style guide.
---
doc/doxygen/headers/coding_conventions.h | 13 +++++++++++++
1 file changed, 13 insertions(+)
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 ;-)
--
2.39.5