FAQ 5.20 What is the best way to create a good interface to an abstraction?

Design the interface from the user's point of view (i.e., design the interface from the outside in). In other words, start by writing some sample user code.

Interface design decisions should be based primarily on the users' external perspective. In contrast, when the implementation is built before the interface is designed, the interface inevitably smells like the implementation. If the interface has to be explained to its users in terms of the implementation, then the implementation becomes cast in concrete.

For example, consider a member function that tells whether a particular integer is in a set-of-int. This is a boolean inspector: it inspects (versus mutates) the set object and it returns a boolean value. A naive name for such a member function might be Set::isElemOf(int) const. However, putting this name in an if statement shows that the name gives the wrong connotation, since the user code reads "if mySet is an element of x":

 if (mySet.isElemOf(x)) ... 

A much better sentence structure would be "if mySet contains x," which means the member function would be named contains:

 if (mySet.contains(x)) ... 

Note that the names of boolean inspectors should imply the meaning of the true response. For example, File::isOpen() const is better than File::status() const.