FAQ 6.04 What are advertised requirements and advertised promises?

An advertised requirement is a condition that the user of a member function must comply with before the member function can be used. Some people use the term precondition instead of the term advertised requirement.

An advertised promise is a guarantee that a member function makes to its users. Some people use the term postcondition instead of the term advertised promise.

When a user fails to fulfill the advertised requirements of a member function, the member function usually fails to fulfill its advertised promises. For example, part of the advertised promise for myStack.pop() is that the number of elements will decrease by one. Therefore the advertised requirements for myStack.pop() will include !myStack.isEmpty() since myStack.pop() cannot fulfill this promise when myStack.empty() returns true.

When users fail to fulfill the advertised requirements, member functions normally throw exceptions. It is also legal, although often less desirable, for member functions to respond more severely to users who fail to fulfill the advertised requirements. For example, if Stack::pop() were invoked in a performance-critical path of the system, testing the advertised requirement might prove to be too expensive, in which case Stack::pop() might advertise, "If the Stack isEmpty(), arbitrarily disastrous things might happen." This is a trust issue: such a statement in the requirement makes it the user's responsibility to guarantee that the preconditions are met prior to the call. This is normally done for performance purposes, where the number of redundant tests and/or the added complexity of those tests would be prohibitively expensive.