FAQ 6.02 Should users of a member function rely on what the code actually does or on the specification?

The specification!

A member function's specification unambiguously defines its externally observable behavior across all possible implementations. The specification of a member function is more than simply the member function's signature. The specification captures the essential service that the member function provides to its users in an implementation-independent fashion. This is an essential part of abstraction and encapsulation. If a class's developers do not provide a full and complete specification, then they have failed as OO programmers because they have failed to properly separate the interface from the implementation and they have forced users to look at the implementation.

Many software organizations systematically fail to observe this critical guideline. Developers in these organizations are trained to rely on what the code does instead of what it promises to do. Users of a member function must be able to rely only on the member function's specification, not on the implementation of the specification. In fact, there are only a few times when users legitimately need to look at the source code to find out what a member function actually does (such as when you are inspecting the code to ensure it fulfills its promise).

In the following example, suppose Version1 and Version2 represent two versions of the same class. Note that the specification (that is, the description of the behavior that other programmers are supposed to rely on) of member function f() did not change even though the implementation of Version2::f() is different from that of Version1::f().

In this case, the specification says that the member function f() "Promises that the return value will be some even number," and presumably this captures the essential behavior of f(). The designer may have done this to allow some implementations to return 4, while other implementations return a random even number between 0 and 100, while other implementations return even numbers less than zero. Users who rely only on this specification won't be hurt by the new version since their code would work for any even number. On the other hand, users who rely on what the code actually does (i.e., who rely on member function f() always returning 4) could break since they may rely on the value being greater than zero or greater than 2 or one of a hundred other assumptions.

 class Version1 { public:   int f();  // Promises that the return value will be some             // even number }; int Version1::f() { return 4; } class Version2 { public:   int f();  // Promises that the return value will be some             // even number }; int Version2::f() { return -2; } 

Never assume that a member function will always do what the code currently does. The code will change, and the specification is generally more stable than the code.