[boost] Re: Property_map docs

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?

Dave