Re: [Boost-users] [boost] Maintenace Guidelines wiki page

Subject: Re: [Boost-users] [boost] Maintenace Guidelines wiki page
From: Robert Ramey (ramey_at_[hidden])
Date: 2008-11-23 11:36:38

Note, that I didn't really want to specifically advocate for any particular
"guideline".  It was an example of the kind of thing
that might be important to a library author but not to a user.  But
I might as well go a little off topic and mention what I had
in miind in these particular guide lines.

>
>> use things like boost/config,
>
> How boost/config helps on maintenace?

boost/config contains all (or most of) the "fix ups" required to make
one's code portable among various compilers and operating systems.
So if one uses boost config rather than his own macros, his
library will automatically be functioning when a new platform
is made available in boost config.  So this helps libraries
cover the widest range of applicability while minimizing
the amount of effort required to achive this.

>> Use Boost.Concepts to help your find mistakes in
>> library usage, etc. are to him.
>
> Could you detail how Concepts helps on mantenance?

I think the usage of boost concepts or something like it would
benefit library authors.  I failed to use it in the serialization
library because I didn't understand how to use it at the time.
I think the serialization library would have been better had I
understood how to use the concept of concepts.  Here is
why I think so.

a) Using boost concept requires that one explicitly state what
the type requirements are for every template.  This can and
should be identical to that described in the library documentation.
This avoids the problem whereby one writes the whole library
and then discovers while writing the documenation that something
doesn't really make sense and that things could be refactors in
a better way.

b) Combined with tests, this means that an interface change
would trap at compiler time.  Now the author who has made
such a change is faced with the extra work of updating his
tests and documentation in order to get things to compile.  He
can't accidently drop in an "obvious" improvement without
realizing that he changed the interface.  This is much easier
to do than it would first appear and I would guess that many
of the incidences where this occurs are in fact accidental.
And of course this would be a huge help to someone other
than the original author who needs to make some change.

c) Maintaining a library whose code, tests, and documentation
are not in sync is harder than maintaining a library which
doesn't have this problem.  Using something like concepts
would make it more  likely that the code in the library is in
sync with the tests and documentation.  This would make
maintenance easier

d) More precise error locations would help support
users and diminish the need for mailing list support.
Technically this isn't maintenance - but it is closely
related since that is how bugs are found after release.

HUGE caveat here is that I've never personally used boost
concepts.  When I really needed it, I didn't understand
the documentation - in large part this is because the
concept concept was a new concept to me.  Now it
seems that this facility will/may be built into future
compilers.  So I don't know if its a good idea
to invest effort in implementing boost concept as it
currently is stands into a current library such as
serialization.

>
And since you've got me started there is a question
about dropping one's own stuff into the boost namespace.

I have a project which uses a couple of boost libraries:
signals, function, thread, variant, integer - not a huge
number of libraries.  This contains the following symbols:

boost::bind
boost::function
boost::variant // might be ok
boost::get - in the variant library
boost::mutex // all the threading types are directly in boost
boost::uint_fast16_t // all these are directly in boost namespace
boost::signals looks like it creates a bunch of boost::signals0, 1,etc.

So far this has only been somewhat confusing.  But, if boost expects
to grow, this practice should probably be discouraged.

>> a user want's to get done with as little as trouble and suprises
>> as possible.  So suggestions like avoiding "using" are helpful.
>> For users, I'm thinking of suggestions similar to "Effective
>> C++, oriented to boost.  Any writing "Effective Boost"?
>
> Could you be more precise?

The only one that comes to mind right now is to avoid
"using" in code which uses libraries.  I'm sure that there
are others that other experienced boost users could
come up with.

Robert Ramey