Edward Diener wrote:
[...]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.
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.
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 toI'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.
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'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
_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
