Boost.MathConstants: Review

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 
resubmitted.