Re: strategy for .h files?

[John W. Eaton]

On 05/01/2017 12:38 PM, Rik wrote:
> 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).

I commented there, but I'll repeat here:

For the files like CColVector.cc, the corresponding header files are 
included because of mx-base.h.

oct-norm.{h,cc} is definitely a weird one...

I assume most of the others eventually include the corresponding .h file 
by way of including some other header. But making that explicit 
shouldn't hurt.

I'll also add that I think I created mx-base.h because it seemed simpler 
than repeating a possibly long list of header files in each of those 
source files.

About a year ago, I started trying to convert those files to use 
templates more effectively, so maybe we could eliminate the need for 
some of those specific classes like ComplexColumnVector and replace them 
with templates instead (column_vector<Complex>.  These files also define 
a number of mixed-type operations, so maybe there is a better way for 
the classes and functions they define to be organized so that the number 
of header files can be limited a bit.

> 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?

I agree that cleaning things up would be good.  I'm not sure what is best.

I generally try to keep the standard includes out of our header files, 
but sometimes you can't get away with a <iosfwd> or some other simple 
forward declaration so they are needed.  The same applies for our own 
headers.

jwe