Utility functions vs non-static member functions
I'm defining an abstract base class as a part of an API that will be used by other developers, kind of like defining the Android API and letting developers use it to make phone apps. **When should the creator of the API (that's me) provide certain functionality, and when should the creator leave it up to the developers (ie. users of the API) to define that functionality?**


Here's a relevant example: let's say I'm defining a general tree of <i>MyObj</i>s (where users can make classes that derive from <i>MyObj</i> and have children, a parent, and can be filtered via types and values.

    class MyObj
    {
     public:
      // These must be provided
      MyObj const * parent();
      bool setParent(MyObj const * i_obj);

      std::vector<MyObj const * > children() const;
      bool addChild(MyObj const * i_obj);
      bool removeChild(MyObj const * i_obj);


      // The following functions can be implemented
      // by using the functions listed above.
      // Should I provide them (by leaving them in the class or
      // defining them as utility functions, etc), or should I let 
      // the developers define them?
      MyObj const * root() const;
      bool hasChild(MyObj const * i_obj) const;
      std::vector<MyObj const * > descendants() const;
      std::vector<MyObj const * > childrenFiltered(FilterType i_type, FilterValue i_val) const;
      std::vector<MyObj const * > descendantsFiltered(FilterType i_type, FilterValue i_val) const;

     private:
      std::vector<MyObj * > m_children;
      MyObj * m_parent;
    };


  

Things to consider:

* If it involves the use of private variables such that the devlopers (users of the API) <i>can't</i> provide that functionality, themselves, then I <i>must</i> provide it. 
* If some functionality will be used by many of the developers (users of the API), define it myself. That way, developer A won't need to make the same set of extremely useful utility functions that developer B makes; they'll both use the ones I provide.
 * On the other hand, maybe it is best to not try to predict <i>how</i> the base class will be used, and instead, provide the minimum functionality needed to allow developers to do whatever they want.
* If the functionality is <i>core</i> functionality, provide it (even it can be implemented using only other public functions)
 * Determining if something is <i>core</i> functionality seems to be a rather vague business

related posts:

* http://stackoverflow.com/a/1055889/635125
* http://www.gotw.ca/gotw/084.htm
* http://stackoverflow.com/questions/135634/class-design-vs-ide-are-nonmember-nonfriend-functions-really-worth-it
 

Utility functions vs non-static member functions
===

I'm defining an abstract base class as a part of an API that will be used by other developers, kind of like defining the Android API and letting developers use it to make phone apps. **When should the creator of the API (that's me) provide certain functionality, and when should the creator leave it up to the developers (ie. users of the API) to define that functionality?**


Here's a relevant example: let's say I'm defining a general tree of <i>MyObj</i>s (where users can make classes that derive from <i>MyObj</i> and have children, a parent, and can be filtered via types and values.

    class MyObj
    {
     public:
      // These must be provided
      MyObj const * parent();
      bool setParent(MyObj const * i_obj);

      std::vector<MyObj const * > children() const;
      bool addChild(MyObj const * i_obj);
      bool removeChild(MyObj const * i_obj);


      // The following functions can be implemented
      // by using the functions listed above.
      // Should I provide them (by leaving them in the class or
      // defining them as utility functions, etc), or should I let 
      // the developers define them?
      MyObj const * root() const;
      bool hasChild(MyObj const * i_obj) const;
      std::vector<MyObj const * > descendants() const;
      std::vector<MyObj const * > childrenFiltered(FilterType i_type, FilterValue i_val) const;
      std::vector<MyObj const * > descendantsFiltered(FilterType i_type, FilterValue i_val) const;

     private:
      std::vector<MyObj * > m_children;
      MyObj * m_parent;
    };


  

Things to consider:

* If it involves the use of private variables such that the devlopers (users of the API) <i>can't</i> provide that functionality, themselves, then I <i>must</i> provide it. 
* If some functionality will be used by many of the developers (users of the API), define it myself. That way, developer A won't need to make the same set of extremely useful utility functions that developer B makes; they'll both use the ones I provide.
 * On the other hand, maybe it is best to not try to predict <i>how</i> the base class will be used, and instead, provide the minimum functionality needed to allow developers to do whatever they want.
* If the functionality is <i>core</i> functionality, provide it (even it can be implemented using only other public functions)
 * Determining if something is <i>core</i> functionality seems to be a rather vague business

related posts:

* http://stackoverflow.com/a/1055889/635125
* http://www.gotw.ca/gotw/084.htm
* http://stackoverflow.com/questions/135634/class-design-vs-ide-are-nonmember-nonfriend-functions-really-worth-it
 
