Criteria for putting functionality in an API or letting developers make it themselves [closed]

StackOverflow https://stackoverflow.com/questions/8946012

Question

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 MyObjs (where users can make classes that derive from MyObj 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 developers (users of the API) can't provide that functionality, themselves, then I must 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 how 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 core functionality, provide it (even it can be implemented using only other public functions)
    • Determining if something is core functionality seems to be a rather vague business

related posts:

No correct solution

Licensed under: CC-BY-SA with attribution
Not affiliated with StackOverflow
scroll top