Intentionally inconvenient API design

If you have worked with the C++ Standard Template Library (STL), chances are that you have used one of its container classes like std::vector, std::stack or std::queue. All those classes, and quite a few more, share a pop method that can conveniently be used to remove the top or front value off the container. Whatever top or front means exactly depends on the type of container.

Much less convenient is the fact that pop does not return the value it removes. Instead of

int v = my_stack.pop();

you have to write

int v = my_stack.top();
my_stack.pop();

A quick online search will give you several reasons as to why it is designed that way. Most prominently

• Efficiency: Since the values get removed, they must be returned by value. This could potentially be expensive.
• Exception safety: Due to return by value, (copy-)constructors could throw exceptions.

While this are most likely the real deciding factors, I have one more argument as to why your pop methods should not return the value. And it is not related to any C++ exception/copy-constructor mumbo-jumbo. In fact, it could just as well bite you in C.

Order of evaluation

Let's take the following example function

int sub(int a, int b) {
  return a - b;
}

In a real code base of mine I actually used a function with similar signature when implementing a stack machine, so the values that I passed into the function were in fact sitting on a stack data structure. I defined my subtraction operation to use the value on top of the stack as the minuend and the value below it as the subtrahend. The pop method of my custom stack class returned the value directly so naturally I called the sub function like this:

int v = sub(stack.pop(), stack.pop());

This code is unfortunately incorrect! According to the C and C++ specification the order of evaluation of function arguments in a function call is not specified. The compiler can very well decide to execute the pop for function parameter b first and a second, resulting in an incorrect result of the subtraction. And this is not just hypothetical. It did cause a bug in my stack machine. And it is not just limited to function calls. All sub-expressions can run into this.

With pop not returning the value it indirectly prevents you from making this mistake in the first place. Most modern languages specify clear rules for the order of evaluation (usually left-to-right) but I think I will stick with my non-returning pop anyways...