Boost logo

Boost :

From: David B. Held (dheld_at_[hidden])
Date: 2002-11-14 15:38:38

Edward Diener wrote:

> [...]
> The problem is that property map is presented separately from the BGL.
> Therefore a valid assumption would be that one could understand how it
> works separately from the BGL.

But not necessarily that one could understand how it works the first
time you looked at the docs. I have a modern physics textbook from a
class I took in college. I like to read it now and then. But I can
turn to any number of chapters, read them five times, and still have no
meaningful understanding of what is written. The text is not poorly
written, and I am not an idiot (though I might have a hard time finding
people to vouch for that!). The problem is that I have weak calculus
skills, and not enough physics background for the book to be more
comprehensible. Sometimes, I just like to read the sidebars that
describe an application of the principles to a real problem, and pretend
that I understand what's going on. Since I'm not a mathematical
prodigy, it is not feasible for me to read a bunch of PDEs and say:
"Well, duh! That's obvious!" In the same way, my understanding is that
the Property Map library is not a library like the RegEx library. There
are no headers to be included, and no source files to be built, any more
than the Iterator concept requires headers or source files.

When I first saw the STL in use, I didn't understand how it worked, or
what its advantages were. I had no clue why anyone needed iterators.
Had I seen a technical discussion of how to produce a
standard-conforming iterator, it would have been worthless to me, no
matter how well written. The problem is that I didn't know what
iterators were all about. Only after seeing many concrete instances of
iterators did I begin to see why they were useful. When I started
toying with STL container implementations, I saw the iterator classes,
but more or less treated them like black boxes. Now, I feel I could
write a custom container and conforming iterators from scratch. But it
would have been no more reasonable for me to demand a clear and concise
explanation of the Iterator concept as an STL novice than it is for
someone to demand a clear and concise explanation of the Property Map
concept as a BGL novice.

> [...] I will say that no matter how poor the documentation seems to
> me, it is probably on another level which I don't understand and which
> others can easily figure out without any more specific explanation. I
> apologize to all concerned and will simply bypass such implementations
> in the future when the language of it is beyond my understanding. I
> thought that by criticizing there would be others who might agree that
> the documentation is not adequate for an intelligent C++ programmer to
> grasp, and there would be an effort by either Mr. Siek, or someone
> else who understands property map, to improve it and make it more
> understandable.
> [...]

I'll be the first to admit that I didn't understand what the Property
Map was all about the first time I looked at it. And the second. And
the third. And I'll admit that I was frustrated that there wasn't a
header file I could look at for a reference implementation. And maybe
the docs could be improved. But the fact of the matter is, programming
is evolving before our eyes. I like to say that you don't understand a
concept until you can explain it to a five year old. That obviously is
a bit optimistic, but the point is this: the best instructors are the
ones who can lecture freshmen, as well as Ph.Ds and Nobel laureates.
And that's because they understand the concepts so well, they can relate
them to the most mundane experiences. I don't think many of the new
ideas in programming, especially in C++ template metaprogramming, are
mature enough for anyone to have that level of understanding. The lack
of good C++ template books says volumes.

I'm sure Jeremy and others had to make up new concepts and ideas as they
went along, building the beast that is the Graph Library. The Property
Map just happened to be one of those unplanned side-products. Yes, the
documentation implicitly targets those "in the know". No, I doubt that
was intentional. Understanding how Property Map works requires the same
kind of paradigm shift involved in understanding how Iterator or Functor
works. The C++ template engine creates a metalanguage that operates on
syntactic form, rather than on concrete semantics. This is why concepts
are described in terms of valid expressions, rather than function or
type signatures.

This notion is not always easy to grasp, and I still struggle with it
quite a bit. The idea of creating a metatype that is only a concept,
and not something we can write in code can be frustrating. But the fact
of the matter is, every real iterator *type* is an *instance* of the
metatype *Iterator*. In the same way, every conforming get()/put()
*definition* is an *instance* of the metatype *Property Map*, even if
they are themselves *template functions*. The fact that we can't write
metatypes that are concepts in C++ is probably the major stumbling
block. The best we can do is write concept checks that validate that a
given *instance* of a concept conforms to the definition of the
metatype. In that way, the Concept Checking Library is the closest
thing we have to a Concept Compiler.

In a way, a Concept is like a protocol. It defines a way to do things,
without enforcing that way explicitly. Any way you can get the job done
is good enough. The internet defines numerous protocols without saying
how they should be implemented. So people write all manner of
implementations, for all kinds of hardware and OS platforms, and because
they agree on the Concept of the internet, they all just work. When
functions named get()/put() agree with Property Map algorithms about
the Property Map Concept, they all just work. If you want a reference
implementation, look at the BGL. If you want a reference implementation
of Iterator, look at std::list::iterator. Yes, you can understand
Iterator without looking at concrete instances. But unless you are an
abstract reasoning prodigy, it might be a little challenging.

Part of the problem is that the audience of Property Map is probably not
enormous. If you think about it, a library is really a
meta-application. It's an application written for programmers, rather
than end users. Concrete types are usually the tools of the trade for
application programmers. But generic and metatypes are the tools of the
trade of meta-application, or library, programmers. Property Map, like
Iterator, is a meta-tool. So while there might be concrete uses of it
in some end-user application, it is more likely to be useful to library
builders than library users. Just like you don't need to write your own
iterator types to make good use of iterators, you generally don't need
to directly use Concept metatypes to make good use of their end
products. For now, the "end products" of Property Map are found in the
BGL. The fact that there are far fewer library writers than library
users implies to me that Property Map will probably have a far smaller
user base than, say, boost::bind or boost::function.

It's nice to admire tools simply for the sake of elegance. But if you
don't have a use for a cuisinart, then maybe it isn't so important that
you understand how it works in intimate detail. I don't know how a good
deal of the Boost libraries work, because I don't have need for them.
When I suspect one could help, I look into it further. But it generally
doesn't bother me if the documentation doesn't spell out in painful
detail how I can use a given library. When I need to use a library, the
documentation usually tells me what I need to know at that time. And
working on a real problem makes the whole affair much easier to grasp.
For someone who needs to understand how Property Map works, the docs may
very well be good enough. Is it really necessary to cater to
*non-users* of the library?


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