Re: [boost] [property_tree review] Making the interface leaner, concretely...

From: Thorsten Ottosen (thorsten.ottosen_at_[hidden])
Date: 2006-04-23 10:51:08

Ivan Vecerina wrote:
> "Thorsten Ottosen" <thorsten.ottosen_at_[hidden]> wrote in message 
> news:444B3FDD.3000404_at_dezide.com...
> : Ivan Vecerina wrote:
> : > I would plainly take out all the member functions labeled as
> : > "Ptree-specific operations" (see basic_ptree in the Synopsis in the
> : > main doc page: http://kaalus.atspace.com/ptree/doc/index.html ).
> : > A first step would be to convert them into a set of non-member
> : > functions (preferably in a separate header file).
> :
> : Why do you think it is an advantage to make these functions non-members?
> : They still mention the property_tree in the parameter list and so are
> : logically still is part of the public interface of ptree.
> : (Thus the claim about lower coupling is somewhat overstated for a
> : library that rarely changes).
> 
> Well, I think that I am of a school of thought defended by Scott Meyers,
> Herb Sutter, Andrei Alexandrescu, and others:
>  http://www.ddj.com/dept/cpp/184401197
>  http://www.gotw.ca/publications/mill02.htm

I'm familiar with Scott's and Herb's views. However, just looking at
Mayer's example

struct Point {
    int x, y;
};

vs

class Point {
public:
    int getXValue() const;
    int getYValue() const;
    void setXValue(int newXValue);
    void setYValue(int newYValue);

private:
   ...                 // whatever...
};

One of my brain-dead teachers back at universoty, showed the first as 
"the C way" and the second as "the superior Java way".

It is certainly true that the latter is more encapsulted than the first.
But it is also true that it is over encapsulated: there is no invariant 
to protect.

Here are some other examples of classes that has been designed
as over-encapsulated:

- std::complex

- standard containers

> : IFACIT, (especially normal) users prefer members. It gives them one
> : place to look for the interface (and is really handy in most IDE's when
> : "." triggers a list of functions). Or we could go back to C and make
> : everything a non-member.
> 
> Very concretely, here, the issue is that we heading for an std::string
> syndrome.  Take a look at c.l.c++ and see how often users want to
> derive from std::string to extend its interface.
> std::string includes about a hundred of member functions (many of
> which overlap with operations available in std::algorithm). Yet it
> will never be enough: users look for trimming functions, case or
> encoding conversion functions, etc etc.
> 
> Do you think that std::string is an example that ptree wants to follow?

No. But I don't see the analogy. A Sequence is a very common concept, 
but a property_tree is not. AFAICT, there's only going to be Marcin's
tree.

> Marcin already has included a large set of useful operations as members:
> there are already 27 functions under "Ptree-specific operations",
> and Marcin has already identified members that he would like
> to add (e.g. 'set' as a complement to 'put').
> Yet they will never satisfy a large enough user base. Some want path
> access with separate strings. Some want path access with '.', or '/',
> or any char as a separator. Some want to escape the separator. Some
> ask for array indexing - embedded in the string, or as a separate
> operation.  And many users may never want to use paths !
> Then there is improved support for arrays (why do I have to push_back
> a pair when I only should specify 'second', the array value ?),
> error handling policies (what happens if a path is ambiguous
> because multiple children are homonyms?), and more.
> How many member functions do we want to have in the end ?
> Will those be representative of the interface subset that
> a majority of users wants to use?

If the free-standing functions are not generic, there is little point
in not making them members. Having free-standing functions like
get/set is a bad bad idea with the current rules for ADL.

> Too many members are confusing too: we had a couple posts already
> from people who were expecting ptree::find to accept paths.

That should be explained by a better toturial.

> No matter how hard you try, you will end up having a mess of a
> large member-interface, yet fail to satisfy the needs of the
> majority.

For one, I'm not suggesting XX new members. Nor am I suggesting XX
new free-standing functions. But for whatever number of interface
functions we find appropriate, I see no compelling reason for not making 
them members and at least two problems with free-standing.

-Thorsten