strategy for .h files?

[Rik]

5/1/17

jwe,

Can we define a strategy for the .h files so there is a goal for what we
want them to do?

In most projects I have seen there is a convention that if there is a
header file XXX.h it is associated with a C++ file XXX.cc.  For starters,
we have lots of instances where this is not true which I find confusing.  I
filed an issue report about that here
(https://savannah.gnu.org/bugs/index.php?50906).

Second, the header file itself can be accomplishing two things.  It can
contain the prototypes and API for XXX.cc.  In this case it is generally
included by OTHER header or C++ files, in addition to XXX.cc.  For this
usage case the header file should be as lightweight as possible since the
pre-processor is going to have to grab and process it multiple times.  The
second case I have seen is that the header file is more about consolidating
and making the code in XXX.cc more readable.  If XXX.cc is using header
files from the C stdlib, C++ stdlib, liboctave, libinterp, and local
includes then there might be as much as a page worth of #includes.  Instead
of having all of that boilerplate in XXX.cc it is abstracted to XXX.h.  And
then XXX.cc has a really minimal include list of "#include "XXX.h".

Both strategies are good, and you can even mix them if you want to do some
grepping and determine which header files are used multiple times
(API-style header file) versus just once (consolidation header).

Any thoughts about what strategy Octave should use?

--Rik