Re: [boost] Tips on writing libraries?

From: David Abrahams (abrahams_at_[hidden])
Date: 2000-12-28 17:56:21

----- Original Message -----
From: "Michael D. Crawford" <crawford_at_[hidden]>

> There are at least two different approaches to writing a library, the
> way I see you folks doing it, in which you attempt to produce an ideal,
> fully general and rigorously verified solution to some problem domain,
> and the way I'm used to doing it that I refer to above - just write a
> program, but when one sees a subroutine or class or template that can
> likely stand on its own, or that only needs what's in the library
> already, then pull it out and put it in the library.

I think you'd better define your terms more precisely. What does it mean to
"put it in the library?"
There are several axes:

packaging (/.a/.so/.lib/.dll file + headers or sources + headers)
implementation reusability (intra-/inter- project, single-/cross- platform,
single-/cross- compiler)
implementation independence (stand-alone, dependent on other libs)
documentation (in your head, in code comments, with exposition/examples)
installation (don't get me started)

That said, I think most successful boost libraries start out as you've
described - a product of a single person's need for reuse. For example,
while we've had some really interesting discussions on threading, we don't
yet have a threading library. For me, libraries start with the rule "never
repeat yourself in code". From there, factoring of common functionality is a
kind of library writing. One step beyond that, you have separation of
factored components into their own source/header files. Further down the
road, the desires to serve others and to benefit from peer review leads to
the current boost practices.

> The formal method is of more general purpose and is more likely to
> produce a more complete solution to some basic problems.  The second
> method is much more ad-hoc and while likely to have holes in it and to
> have problems when the library is taken out and used for a new purpose,
> I think it's more likely to get more people to contributing code that
> way.  I think the ad-hoc way is of use to a company trying to grow a
> technology base, and in the open source community this technology base
> could be of impressive size and functionality.

I worry a bit about the future of open-source code, because so much of it is
done on an ad-hoc basis. The documentation is generally weak. Will it
collapse of its own weight?

> I think Advogato's dan is write that it is hard to write a truly general
> purpose, complete and coherent library - but even so, it is something
> that can be learned.  Unfortunately, a lot of programming texts cover
> lots of advanced topics and then go on to say "but writing libraries is
> much harder than this, and is beyond the scope of this book".  I think
> that's wrong - even if writing the _best_ library is hard, libraries can
> be improved upon if we have some code to start with, and it's terribly
> difficult to extract a library out of an application that wasn't written
> with libraries in mind in the first place.

I think you have the right idea. It's extraordinarily difficult to write an
application of any complexity without applying the principles of library
design.

> I'd like to work to improve the situation.

I hope we can help.

Regards,
Dave