Framework Design Guidelines: Avoiding Abstractions

Continuing in our weekly blog post series that highlights a few of the new image[5]_thumb[2]_thumb[2]_thumb_thumbadditions to the Framework Design Guidelines 2nd edition..

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.

Comments (15)

  1. Andreii says:

    Guys, you’re doing nice business by publishing interesting info at this site. But you sometimes just clutter your page space by posting installments of the above kind. These small fragments don’t make much sense when just taken from arbitrary places in the original book. After reading the second installment from ‘Idioms…’ book I have a feeling that info not complete and in its current it brings no value to me. Probably, other readers will join my opinion. Don’t make us think that we’re reading nothing but small, single page-size long portions from, say, ‘Peace and war’ kind of books.

  2. BradA says:

    Thanks for your comment Andreii..  I picked out a few nuggets from the book in order to help folks assess if they wanted to buy it or even let them have the information in a more easily accessible way.  I tried to make each one fairly self contained, but maybe I didn’t do such a hot job at it…  But my feeling is the book really is a set of small nuggets with some themes around it..

    Do other find these posts useful?

  3. Francois Ward says:

    Yeah, I think they’re fine. As you said, the book is really a bunch of small nuggets like that. It is written in a much different style than most books you’ll see around lately, so maybe it throws people off.

    While I find the above perfectly fine, I may be biaised because I -have- read the book from cover to cover (well, the original edition anyway).

    Maybe sticking to the DOs and AVOID and stuff from the book may be easier for those who did NOT read it to grasp, but thats just a guess.

  4. Shail says:

    Hello Brad,

    This book is really valuable to me and my career. Your weekly posts on the book, keep me motivated to read the book further. Also its a kind of checklist and status check.

    I am a new Architect and I need to learn as much as I can. Specially the annotations or nuggets whatever you call, they are most helpful. As they come from people who really practice it. This fills the Gap between theory, practice and real world situations The best thing in all of these writing is that people like me can learn from people like you, who have faced tough situations. We should take your experience as base and lay down Architecture for future.

    Please carry on with writing weekly posts :)



  5. Javier says:


    I side with Andreii.  The statement of "too many abstractions" is too vague.  What do abstractions mean? Interfaces? Abstract classes? Associations?

    The only comment that makes sense to me is Krzysztof’s because I’ve seen it in real life, but again, what constitutes a "self-documenting" object model? Don’t know exactly but I can tell you when I see one?

    Vance’s comments don’t make sense to me because STL is about separating the data from the algorithms through the iterators…well, you kinda need to abstract the requirements for the data types, the characteristics of the iteration to place more or less requirements on the types, and the algorithms as to what kind of iterators they would need to perform their thing…and a few functors.  This is not necessarily "bad engineering."  As we all know, the STL has been a very good piece of engineering for a long come–perhaps showing its age now that paralell programming is fashionable.  The complexity does not bother me; on the contrary, it allows me to combine, mix and match.

    More explicit advice, such as how the -ilities of a framework change would help in describing it.

    These are characteristics of self-documenting object models (in my biased opinion):

    – Self-documenting object models use sound OO design principles.  What comes to mind is Open-Closed Principle, Dependency Inversion principle, Liskov’s Substitution Principle.

    – Self documenting models use architectural and design patterns.

    – Self documenting models are navigable. ClassA.PropertyB.PropertyC, etc.

    And even with that, they’re all questionable–as in what do you mean by the Liskov Substitution Principle and how is it achieved in practice 😮


  6. David Nelson says:

    I own the original Guidelines and for the most part find it very useful. However, as happens occasionally in the original, these particular annotations don’t add any value at all to the guideline itself. Statements like "abstractions are a double-edged sword" are arbitrary and meaningless without some kind of context (pretty much any technique or pattern in programming is a double-edged sword). Backing up this "avoid" guideline requires answering two questions: WHY should "many abstractions" be avoided (i.e. what is the downside), and HOW MANY is too many? Obviously there is no single answer to either question, but anything that is not at least attempting to shed some light on them is just fluff.

    The annotations by Krzysztof, Vance, and Chris are vague and unhelpful. Jeff at least tries to address the point, but again there is no context. What does "heavily" OO mean? Was a fourfold decrease in speed significant in the domain of the application? Were there other gains in other areas of performance measurement or in usability and maintainability of the code that were worth the drop in speed? Was the speed loss entirely due to the fact of an OO design, or was it also due to poorly architected or implemented OO code? Obviously I don’t expect Jeff to expound on all of these details within the annotation, but without them its a meaningless anecdote, and doesn’t add any value to the discussion about avoiding many abstractions.

  7. Andreii says:

    Brad, I’ve just read what I wrote yesterday in my post and I found it a bit of agressive style:) That’s not true though it may look like that, so accept my appologies. Anyway, to make these nuggets more useful in terms of making the readers take well-sound decisions whether to buy the book or not, maybe you select more ‘self-contained’ nuggets? I mean here nuggets that when taken out of the overall context look still self-contained, i.e. not requiring referencing the rest of the book for the complete picture. Personally, I’m willing to purchase that book as I’ve read many installments from the first edition. But if I only had have these nuggets I’d be hesitating much when considering purchase.

    Thanks, Brad!

  8. Tom says:

    I think Jeff’s comment on heavy OO design is misleading. It implies that the cause of the slowdown was somehow "overdoing" OO. Heavily focusing on OO should lead to performance and cost benefits. If you get something else out of it, your design is flawed, not the approach. OO never implies that you are ought to create massive hierarchies and extremely complex models. I think the customer in question just tried to apply design patterns without understanding how to use them.

  9. You have got to be kidding right?

    Software is about abstraction. Abstraction is the reason we are not

    programming usking ones and zeros. Abstraction is the place where we can improve the way we do things today and make them better. Abstractions makes the code easier to understand, easier to split up and easier to test. Avoiding abstractions gives us the opposite.

    Some abstractions are not very good, I must admit. (like renaming ArrayList to List. giving an abstract name to a real class is misleading i think. The real abstraction is the IList which was there in the first place). Abstractions is what makes us able to simplify code and realize where we can improve.

    JEFF PROSISE claims that abstraction is bad for performace. It might be so, but lack of abstract is also bad for performance. Without abstractions you will have much more code. It will be difficult maintain and you will quickly end up with something that performs badly.

    I think you mean that one should avoid bad design and not abstractions. :)

  10. Rune Juhl-Petersen is 100% right here, however to be fair to the authors, I think the point is simply ‘poorly concieved, executed, misguided or simply stupid’ abstraction.

    This post however is one of the worst titles I have seen this year, as I thought it was a joke. I’m sure someone I work with may may try to argue this ‘position’ in a future design session. Usually the same people optimizing while they code anything.

    If anything the title should be ‘The imperitave for intelligent abstraction’.


  11. "name" is not a valid attribute of the "pre" tag, it takes some tweaking, but you can get the code highlighting to work without breaking standards.

    generall what i do is something like <pre class="code csharp"> and have it look for call pre tags with a class of code.    

  12. Jim Anderson says:

    I like the "nuggets" as I find the information useful by itself and easy to quickly consume.

  13. The Danish Dynamo says:

    No No No No – Abstractions are your friends! Abstractions keeps the complexity of a system constant, and easy to test. Just make sure that the level of abstractions are consistent within a layer, and that each layer of abstractions, is a level higher than the lower layer, and that the layer interface is well defined and documented. Avoid strong coupling and promote cohesion. Great examples of abstractions are ISO/OSI Network Model, The Computer. The design pattern for abstractions is Domain Model, the alternative is transaction script. Don’t start with high level abstractions, start with the low level building blocks, and you will end up with a great abstraction called "An Application".

    Instead; avoid generalizations!