[Dune] Usage of Barton-Nackman in DUNE expecially for documentation purposes

[Markus Blatt]

Hi,

due to current events, I would like to start a discussion about using
the Barton-Nackman-Trick in DUNE.

First of all, I think all Dune-Developers are quite familiar with this
trick therefore I will skip an introduction about this. It is (and
particularly was) haevily used in DUNE.

When I first heard about the trick, I was rather amazed about what you
can do with this simple trick and tried to use it where ever I could
(mostly without thinking about whether it is convenient to the user of
my code or not). Looking into old code (written by me) I am no rather
annoyed of the usage at many places. And defending that design against
users looking for usability is rather cumbersome. (Actually they are
right, code using this trick not easily usable)

Probably I am not the only one who made this experience.

Mainly I think the Barton-Nackman Trick tries to combine generic and
objectorient programming as you specify the interface in the base
class and implement in the inherited class (objectorient inheritence)
while still taking advantage of the speed you get by the static
polymorphismen.

For the user the usage between the purely generic version

template<class T>
void alogrithm(T& t);

and the Barton-Nackman version

template<class T>
void algorithm(BartonNackmanInterface<T>& t);

does not seem very different as the template parameters do not have to
be specified but get determined by the compiler.

This drastically changes if the Barton-Nackman class has more than one
parameter or/and the user has to write the implementation himself.

In the case of the communicate() methode in the DUNE grid interface, I
think this difference in usability becomes clear at once looking at
the changes that have to be made to adapt code to new interface.  

Instead of writing:

class AccumulateBCFlags{
public:
  typedef std::pair<BCBlockType,VBlockType> DataType;
  ...
};

one now has to write:

class AccumulateBCFlags : 
  public  CommDataHandleIF<AccumulateBCFlags,std::pair<BCBlockType,VBlockType> > {
public:
  typedef std::pair<BCBlockType,VBlockType> DataType;
  ...
};

I think from the usability point of view this is a difference making it
rather more difficult to write code.

Changing from onre style to another is really a pain in the ass to
users (especially during feature freeze).

Another point about usability is that if one method of the interface
is not implemented using Barton-Nackman one gets a segmentation fault
while using the pure generic way this results in a compiler
error. Thus debugging is very much harder using Barton-Nackman.

So let us come to one point where Barton-Nackman is IMHO useful:

It is very easy to provide default implementations of methods (which
might not be optimized for the specific case, but still ok). Thus
releasing the User or Developer from the burden of constantly
reinventing the wheel for each special case and still give him the
possiblity to rewrite some methods to gain more efficiency for his
special implementation.

I think this is one of the main reasons that justifies the existence
of Barton-Nackman. Probably also the cause for usage in Dune.

The Barton Nackman trick is definitely not intented to  get rid of
doxygend limited possiblities to document template parameters and thus
confronting the user with hard to understand interfaces and making him
write code that is hard to debug.

We should not use it that way. As there are other possiblities to
document with doxygen:

- Describing the concepts the template parameter has to adhere to in
  prosa. (This is a compromise but of course lacks all features of
  doygen documentation for normal classes)
- Writing a interface class (or better an example implementation) with
  nice doxygen documentation and saying that the template parameter for
  method algrithm has to provide the interface of that class. Thus
  doxygen will create a link to that class and everything will be fine

Applying the latter possibility would have saved quite some time,
today. 

Markus
-- 
DUNE -- The Distributed And Unified Numerics Environment 
<http://www.dune-project.org>