Boost logo

Boost :

From: Ed Brey (brey_at_[hidden])
Date: 2001-04-19 10:18:50

Boost.MathConstants does a good job of achieving its goal of
providing the highest-precision math constants possible.

A major issue with the implementation for review is that it is poses
a higher bar for entry than necessary for a typical user to use the
library. In particular, there is no header a user can include to get
a nicely namespaced set of constants (as far as I can tell from
the .zip file in the vault). Instead a C header is presented, and
suggestions are given on how the C header can be wrapped to make it
C++ friendly, leaving the user with a lot of reading and potentially
work to do.

For a boost library, a C++ header should provide a clean C++
interface right out of the box, and the user should be burdened with
nothing more. I realize that a library like this might also be
useful for C users; however, boost isn't the right place for such a
library, and so C compatibility must not come at the cost of
complicating a C++'s users experience.

The documentation does a good job of explaining the rational for many
design decisions. A large area left unexplained is why the interface
is not simply:

namespace boost {
  namespace math {
    template<typename T>
    struct constants {
      static T pi() {return T(3.1415...L);}

where a typical user experience would be documented as this:

typedef boost::math::constants<float> c;
std::cout << "Baseball and apple " << c::pi();

If there is a good reason to have anything more than this, the reason
should be given in the rationale section.

The documentation would better server the users if it were structured
with these sections: the interface style, a sample usage, a complete
list of constants available, and then finally a rationale section for
those who care. The existing "How to user this file?" section can
pretty much all go away - the user shouldn't need to worry about the
details presented there.

The files that generate the C++ header defining the constants should
be completely off to the side as far the end user is concerned. They
should be effectively treated as implementation detail
documentation. The boost distribution should include a pre-
generated .hpp file. In fact, a binary boost distribution (no source
code except headers) would not include the generation source at all.

Comments on the names of the constants:
- If there is a good reason to have constants for 1., 2., etc., it
should be documented in rationale. I can't see any use.
- sqrt is not consistent with cubed_root.
- For constant names, it would be nice to user decimal numbers where
the numbers would otherwise be spelled out, e.g. log_3 vs.
log_three. I realize that this gets tricky for one_third, so overall
I understand if for consistency it is better to just spell out almost
all numbers.
- Naming doesn't follow a completely consistent pattern, e.g.
half_sqrt_two is inconsistent with two_pow_three_div_two. (Why not
half_pow_two_thrids or two_pow_three_halfs, depending on what the
latter is supposed to be?)

In summary, I recommend that Boost.MathConstants not be accepted into
boost in its present form. I would like to see it refactored and

Boost list run by bdawes at, gregod at, cpdaniel at, john at