On splitting headers (Re:Objectionstoremovingtheoldsmartpointerclasstemplates?)

From: vesa_karvonen (vesa_karvonen_at_[hidden])
Date: 2002-02-05 16:29:16

--- In boost_at_y..., Beman Dawes <bdawes_at_a...> wrote:
> At 03:16 PM 1/30/2002, vesa_karvonen wrote:
>>In my experience, any header which contains the interface of more
>>than one thing ends up being splitted or consumes compiling time
>>unnecessarily. Boost has many headers which have more than one
>>interface.
>>
>>I think that it would be beneficial to make it a guideline in
>>Boost to split components into headers so that every client of a
>>header is expected to use all components declared in the header.
>>
>>I always shiver when I need to include <algorithm> in order to
>>use max() or min().
> 
> But that is only one side of the equation.  The other side is the
> various costs that are known to occur with overly fine-grained
> headers.  All of the following costs have been reported from the
> field:
> 
> *  Increased errors by inexperienced programmers.  The saddest
> reports are the cases where the new programmer assumes the problem
> is his or her fault, and destroys the program in the process of
> trying to discover what the compiler is complaining about.

I agree that this is indeed sad...

> *  Increased errors by experienced programmers.  Experienced
> programmers recover immediately, but still complain of what is seen
> as an unnecessary burden.  The STL headers have been cited as
> specific examples of overly fine-grained headers.

...splitting existing headers does indeed cause some grief. That is 
why headers should be atomic in the first place. Then there will be 
no grief caused by change as is happening now with Boost.

I'd like to see references to articles/whatever that complain about 
STL headers being overly fine-grained. Not that I would doubt such 
would exist, because I can certainly imagine some people complaining 
about the subject.

> *  Difficulty teaching.  Teachers apparently don't want to have to
> explain  much of the details of headers until later in a
> programming course.  Fine-grained headers get in the way of this.

Perhaps. I must admit that I fail to see the difficulty of teaching 
how to use #include. It shouldn't take many minutes.

> *  Intimidation factor.  Potential users of a library can be scared
> off by a large number of headers.  A potential Boost user decided
> against use because "Boost is for experts only - look at the number
> of headers."

What can I say, sad.

> *  Header dependency metric.  Header dependency is sometimes
> measured, with a high numbers of dependencies seen as bad
> practice.  Harder to avoid with fine-grained headers.  Very similar
> to intimidation factor.

Dependencies should not be measured in numbers of headers. It is a 
useless metric.

Ideally dependencies should be measured in how long it takes for the 
compiler to process the dependencies. Since lexing (and parsing) 
typically consumes most of the time taken by the processing of 
headers, an easy to compute, rather portable and usable metric is the 
bytes of code metric.

> *  Increased compile time.  Depending on the performance
> characteristics of  the platform (particularly, slow to open
> files), large numbers of small headers can take longer to compile
> that larger granularity headers.

It is most unfortunate that we don't have the necessary data to make 
any real conclusions here.

My bet, which, I believe, is supported by John Lakos, is that the 
incremental development of large software systems can be made 
considerably more effective by using fine grained headers than 
coarsely grained headers. What I'm ultimately getting at is that 
modification of a single header should cause the recompilation of a 
minimal number of translation units. This simply can not be achieved 
by using coarsely grained headers.

I'd love to provide more arguments in favour of fine grained headers 
here, but unfortunately I have to go to sleep now.