[documentation]Need for "programmar's guide" or "tech notes"

Periodically, and probably inevitably, someone thinks of a possibly better way to do something in a boost library. For example, I recently got the "brilliant" idea to maybe use inheritance to check whether an item was already in an mpl::set and thus reducing, what I assumed, was at least a linear time complexity for the has_key metafunction. Although: http://www.boost.org/libs/mpl/doc/refmanual/has-key.html claims "Amortized constant time" complexity, I assumed the compiler has to do a linear lookup at least once for each has_key instantiation. After that, for each occurrence of the has_key with the same template arguments, I guess the compiler has a constant time (using a hash map?) method for finding the instantiation. Anyhow, that was my motivation. The basic idea idea was to use inherit2<Member,TailSet> where Member was the Member to be inserted into a set, and TailSet was the members inserted before Member. Then has_key would simply use type_traits is_base_of<Member,TailSet> to see if Member was a member of TailSet before doing the insertion. If it was already a member, the just return TailSet, if not, then return inherit2<Member,TailSet>. Of course, before starting to code, I thought it might be a good idea to see how mpl currently implemented the associative containers in case this idea was already being used :) However, when I looked at the mpl code to try to understand the the implementation, I got lost. For example, the output from cpp produces: # 25 "/home/evansl/prog_dev/boost-cvs/ro/boost/boost/mpl/set/aux_/has_key_impl.hpp" 2 namespace boost { namespace mpl { template <> struct has_key_impl <aux::set_tag > { template < typename Set, typename T > struct apply # 47 "/home/evansl/prog_dev/boost-cvs/ro/boost/boost/mpl/set/aux_/has_key_impl.hpp" : bool_ < (sizeof (Set:: is_masked_ (aux::ptr_to_ref (static_cast < Set * >(0)), static_cast < aux::type_wrapper < T > *>(0))) == sizeof (aux::no_tag)) > { }; }; } } # 19 "/home/evansl/prog_dev/boost-cvs/ro/boost/boost/mpl/set/aux_/at_impl.hpp" 2 I couldn't figure out the purpose of static_cast or Set:: is_masked_ ; however, it seemed there was no counterpart to inherit2; so, I assumed I wasn't reinventing the wheel (of course I "conveniently" didn't notice that apparently no linear time complexity was involved). So, I forged ahead an implemented it ; however, I then realized that has_key<inhert2<Member,TailSet>,TailSet> would return true since TailSet was a supertype :( OK, so then I thought maybe using the template argument deduction method in section 9.10 of _C++ Template Metaprogramming_ (alias _C++TMP_) would avoid this. That's now in the boost vault under the "Template Metaprogramming" directory. Then I thought again. Using _C++TMP_ section 9.10 used a static_cast also; so I looked further in the cpp output and found: static aux::no_tag is_masked_ (s_item const &, aux::type_wrapper < T > *); and OOPS!, it was looking more like I'd reinvented the wheel after all :( (I'm not totally sure, but it looks like that's what was done. Please let me know if that's wrong.) A "programmer's manual" describing, at least briefly, the implementation, would help future redesigners find their way and avoid the pain of reinventing yet another wheel. This was called "technical notes" before: http://archives.free.net.ph/message/20051006.180034.8cd1ece3.en.html

Larry Evans wrote:
A "programmer's manual" describing, at least briefly, the implementation, would help future redesigners find their way and avoid the pain of reinventing yet another wheel. This was called "technical notes" before:
I disagree. Such a manual would be a possibly considerable additional effort with minimal returns. If someone feels the need to reimplement a part of a Boost library, they might as well read and understand the code. However, better comments in the code that explain the confusing parts (and the Boost libraries contain lots of confusing and roundabout code) would be generally a good idea, simply for future code maintenance and debugging. Thinking about it, I'm probably just arguing that such a manual should not be an external document ... Sebastian Redl

Sebastian Redl <sebastian.redl <at> getdesigned.at> writes:
Larry Evans wrote:
A "programmer's manual" describing, at least briefly, the implementation, would help future redesigners find their way and avoid the pain of reinventing yet another wheel. This was called "technical notes" before:
I disagree. Such a manual would be a possibly considerable additional effort with minimal returns.
... for the author
If someone feels the need to reimplement a part of a Boost library, they might as well read and understand the code.
I have read Eric Niebler's splendid article http://www.artima.com/cppsource/foreach.html Then I took a look at the bost implementation and could not find any similarity at first glance. OTOH foreach.hpp is clean and cute code compared to all the files that heavily rely on boost::preprocessor, which nearly always is write-only code. See e.g. boost::fusion stuff or boost fusion docs. "Effective boost::fusion" is yet to be written. So I really appreciate the fact that Eric took the time to explain why he did it and how, since the techiques he describes will save me one day. But it would be much better to have this article distributed as part of the boost library as well, since I stumbled over Eric's article only by chance while searching for something completely different. Read and understand code like the stuff in boost::fusion where some 3-week discussion about compile-time complexity between the 4 best C++ programmers around the world is boiled down to the essentials and then obfuscated with some macros is merely impossible. I had big hope in the book from David and Aleksey (http://www.aw-bc.com/catalog/academic/product/0,1144,0321227255,00.html), but it is way too short and gives not enough details. OTOH I can really understand that it is hard work to get things boiled down for the uneducated like me. This is why everyone kisses Scott Meyer's feet: he is able to EXPLAIN the what and why - and he (or Addison-Wesley) gets a lot of money (from me) for this ...
However, better comments in the code that explain the confusing parts (and the Boost libraries contain lots of confusing and roundabout code) would be generally a good idea, simply for future code maintenance and debugging.
Thinking about it, I'm probably just arguing that such a manual should not be an external document ...
A detailed analysis and explanation of all BOOST_MACROS probably is a step into a good direction ... Markus

-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Sebastian Redl Sent: 07 January 2007 18:17 To: boost@lists.boost.org Subject: Re: [boost] [documentation]Need for "programmar's guide" or "tech notes"
Larry Evans wrote:
A "programmer's manual" describing, at least briefly, the implementation, would help future redesigners find their way and avoid the pain of reinventing yet another wheel. This was called "technical notes" before:
I disagree. Such a manual would be a possibly considerable additional effort with minimal returns. If someone feels the need to reimplement a part of a Boost library, they might as well read and understand the code.
However, better comments in the code that explain the confusing parts (and the Boost libraries contain lots of confusing and roundabout code) would be generally a good idea, simply for future code maintenance and debugging.
I agree with this - as a reader of the often rather subtle Boost code (often obfuscated by portability constraints), I think there is a generally sub-optimal level of comments. Perhaps reviewers can note things that could benefit from more comments? Paul --- Paul A Bristow Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB +44 1539561830 & SMS, Mobile +44 7714 330204 & SMS pbristow@hetp.u-net.com

Larry Evans <cppljevans@cox-internet.com> writes:
and OOPS!, it was looking more like I'd reinvented the wheel after all :( (I'm not totally sure, but it looks like that's what was done. Please let me know if that's wrong.)
Looks like it. The key is to replace "manual" list traversal with overload resolution.
A "programmer's manual" describing, at least briefly, the implementation, would help future redesigners find their way and avoid the pain of reinventing yet another wheel. This was called "technical notes" before:
http://archives.free.net.ph/message/20051006.180034.8cd1ece3.en.html
Yeah, that would be great, wouldn't it? :) But who has time? -- Dave Abrahams Boost Consulting www.boost-consulting.com
participants (5)
-
David Abrahams
-
Larry Evans
-
Markus Werle
-
Paul A Bristow
-
Sebastian Redl