Formal Review: Concept Checking

From: Beman Dawes (beman_at_[hidden])
Date: 2000-11-20 10:37:04

The Concept Checking library should be accepted by boost.

I expect we should develop a policy about when to use concept checking, and 
then go back and apply it to many of our existing boost templates.

Good work, Jeremy!

--Beman

[This review is based on reading the documentation.  I haven't tried to 
actually use the implementation.  Hopefully, some other reviewer will try 
actual use.]

Major issues
------------

*  I think the documentation needs to be reorganized to emphasize use of 
concept checking and the Boost Concept Checking Library (BCCL) as an 
everyday tool for template developers.

As it stands now, a casual reader could easily get the idea that concept 
checking is a just minor implementation technique to produce more 
meaningful compiler error messages, and that it applies mostly to the C++ 
standard library, or even just to the SGI STL library.

It seems to me the primary benefit of the BCCL is to focus a template 
designer on making explicit the requirements that are implied by every 
template parameter.  View it as a design discipline rather than an 
implementation technique. A way to make the contract with the template user 
explicit.  The code becomes more self-documenting, too, which is often 
desirable.

*  Tutorial material, rationale, and reference material are all lumped in 
the same document.  They should be separated.  The reference material 
itself covers several different topics - checks, canned concepts, 
archetypes, etc. - and these might even be separate pages.  The experience 
BCCL user will just be looking up the exact name of a particular canned 
concept, for example, and should be able to reach that quickly.

*  More of the examples (or at least the first examples) should be for user 
applications rather than C++ Standard Library implementations.

*  Grep for "Standard Template Library", "STL", and "SGI".  Many of these 
references should really be references to the C++ Standard Library, Matt 
Austern's book, or ???.  We don't want to ignore the importance of SGI's 
contributions, but where possible we should reference ISO or public sources 
rather than a particular Standard Library implementation.  To be blunt, the 
SGI web site could be gone tomorrow, too.  (But I don't know what to do 
about links to the SGI site for individual concepts. Ideas?)

*  Should BOOST_REQUIRE (currently REQUIRE) et. al. be renamed 
BOOST_FUNCTION_REQUIRES?

    -- Would be consistent with BOOST_CLASS_REQUIRES.
    -- Name is more specific to usage.
    -- Doesn't use up the REQUIRE macro name.

*  The concept names are easy to confuse with template parameter names:

      template <class RandomAccessIter>
      void stable_sort(RandomAccessIter first, RandomAccessIter last)
      {
        REQUIRE(RandomAccessIter, RandomAccessIterator);

    How about appending Concept to the visible concept names:

        REQUIRE(RandomAccessIter, RandomAccessIteratorConcept);

    Presumably then _concept doesn't have to be internally appended, and 
the naming becomes more consistent in docs, class browsers, etc.

*  The Reference documentation is way under-specified, IMO.  It should be 
possible to read it without plowing through the discussion.  (Although it 
should be complete, it can be very terse, essentially written in 
standardese.)

Minor issues
------------

*  Minor work on headers:  Add title comment, add reference to boost web 
site. Add BOOST_ to macros.

*  In Motivating Example, "The output from other compilers is listed in the 
Appendix."  The appendix appears to be missing.

*  In Using Concept Checks, "gives and example" should be "gives an 
example".

*  In Using Concept Checks, the stl_concept_checks.cpp example seems 
contrived.  A much more likely example of uncertainty is not something like 
"typedef std::vector<int> Vector;"  but some unfamiliar non-standard 
library supplied Vector.  Maybe it was just me, but I found the example 
unconvincing.

*  In Creating Concept Checking Classes, would a concept from some library 
other than the Standard Library be more likely to resonate with a potential 
template implementor?

*  In Reference, there is no indication of which component comes from what 
header, or what namespace.

*  In Reference, the "UNDER CONSTRUCTION" material needs to be supplied.

Non-issues
----------

*  The use of macros seems justified.  Maybe eventually someone will see a 
pattern to all our compile time (or instantiation time) macro uses and 
propose a language feature that will subsume them.

-- end --