This content is found in the Principle of Self-Documenting Object Models section of Chapter 2: Framework Design Fundamentals. I love the war-stories that our annotators provide here.
AVOID many abstractions in mainline scenario APIs.
Abstractions are almost always necessary, but too many abstractions indicate over-engineered systems. Framework designers should be careful to design for customers, not for their own intellectual pleasure.
A design with too many abstractions can impact performance, too. I once worked with a customer who re-engineered its product to incorporate a heavily OO design. They modeled everything as a class and ended up with some ridiculously deeply nested object hierarchies. Part of the intent of the redesign was to improve performance, but the “improved” software ran four times slower than the original!
Anyone who has had the “pleasure” of debugging through the C++ STL libraries knows that abstraction is a double-edged sword. Too much abstraction and code gets very difficult to understand, because you have to remember what all the abstract names really mean in your scenario. Going overboard with generics or inheritance are common symptoms that you may have over generalized.
It’s often said that any problem in computer science can be solved by adding a layer of abstraction. Unfortunately, problems of developer education are often caused by them.