Skip to content.

Personal tools
You are here: Home » Members » chrism's Home » Tips for Greenlighting a Framework

Tips for Greenlighting a Framework

When should you write a new framework?

Creating a framework takes an incredible amount of hubris. When you create your own framework, you appear to be saying these things:

  • The set of contracts offered to you by the other 200 frameworks of the same kind are wrong.
  • I know what the right set of contracts is.

This assessment of the pigheadness of creating a new framework isn't quite right though. What you're really saying when you create a new framework is:

  • The set of contracts offered to me by the other 200 frameworks don't fit my brain, or I can't figure them out.
  • I know what the right set of contracts is for me.

Thus, it's never a-priori pointless to create a framework. It's always an option. In a world of poorly-documented, poorly-tested, poorly-designed frameworks, sometimes it's just required. But it is pointless to create a framework if you advertise it as something that other people should use and any of the following conditions are true:

  • It doesn't need to be a framework.
  • You write no documentation for it.
  • You write some good, incomplete documentation for it.
  • You write bad documentation for all of it.
  • You write no tests for it.
  • You write some good, incomplete tests for it.
  • You write bad tests for all of it.
  • Your API design skill are poor.
  • You have no intention of maintaining the software in the future or you have a record of abandoning projects quickly.
  • You can't stand criticism.
  • You're relying on directly making money from its sale or adoption.
  • You completely reinvent the wheel; your framework is largely indistinguishable from some other non-pointless framework.

By this set of criterion, some percentage of the web frameworks listed on the Python wiki are indeed pointless. But although the very last bullet point condition in the above list ("you completely reinvent the wheel...") is often cited as the primary reason that writing another web framework is a bad idea, most of the web frameworks on that page can't be discounted as pointless for this reason at all. Most are quite novel, and contain new ideas, and many solve some web development subproblem better than any another. Instead, web frameworks can more often be categorized as pointless for some combination of the other reasons in the above list: didn't need to be a framework, no docs, bad docs, no tests, bad tests, bad API, bad maintenance record, or inappropriate expectations.

As someone who has written a good number of frameworks (many of which have utterly failed), I'll try to offer some tips for people thinking of writing their own framework. Using these tips doesn't guarantee success, but failing to heed them seems to almost certainly guarantee failure.

Tips for checking that your idea even rates being a framework at all

  • You've written the same code at least 20 times in your programming career.
  • It doesn't make sense as a library.
  • No, really. It really doesn't make sense as a library.
  • The problem that your framework solves should largely represent a career choice.
  • If the framework doesn't represent a career choice, it better be damn small.
  • If someone tells you this shouldn't be a framework, they might be right.
  • If someone tells you this shouldn't be a framework, they might be wrong.

Some tips for writing docs

  • Write them.
  • Write them in English (even if it's not your mother tongue, sorry).
  • Write them in clear English.
  • Write them in clear, engaging English.
  • You need to document everything.
  • You need to document everything, even the stuff you don't think you need to document.
  • When someone complains about something not being documented: remember, you need to document everything, even the stuff you don't think you need to document; write docs in clear, engaging English.
  • Keep the docs up to date.
  • When the docs are out of date, fix them so that they're back in date.
  • Keep around versions of docs that relate to versions of your framework; not everybody uses the newest one.
  • Doctests aren't docs.

Tips for writing tests

  • Write them.
  • Write them in Python.
  • Write them in clear Python.
  • You need to test everything.
  • You need to test everything, even the stuff you don't think you need to test.
  • When someone complains about something not being tested: remember, you need to test everything, even the stuff you don't think you need to test.
  • Keep the tests up to date.
  • When the tests are out of date, fix them so that they're back in date.
  • Doctests aren't tests.
  • Run the tests often.

Tips for writing APIs

  • More API is never good. Adding an API should be a momentous occasion.
  • Less API is usually good, but only if it's not too little.
  • APIs are contracts: break them at your peril.
  • Coddling a bad API forever is worse than breaking a contract.
  • APIs that take a lot of arguments are usually bogus.
  • Sometimes big, bogus APIs are just what the doctor ordered, though, if it means that people need to remember less.
  • When your fingers type the wrong thing, they're usually righter than your brain. Fix your API instead of retraining your fingers.
  • Features are the enemy.
  • Libraries are better than frameworks.
  • Frameworks are better than failure.
  • Requiring that a user subclass a framework-defined class is almost always the wrong answer.
  • Requiring use of a framework-defined decorator is almost always the wrong answer.

Tips for maintenance

  • If you usually start things and don't finish them: don't do it.
  • Maintainance sucks.
  • You have to do maintenance, even though it sucks.

Tips for expectation-related things

  • You won't make any money from this.
  • If you make some money from this, consider it a freak accident.
  • Criticism is healthy. It means someone cares enough to even try your code. Treat criticism as massive success.

Have fun with your new framework!

Created by chrism
Last modified 2010-03-15 07:45 PM

Frameworks, hubris and private religions

As a person whose world-view of frameworks largely formed while within spitting distance of Chris (note no spitting actually occurred to my recollection) this topic certainly resonates with me. I tend to agree with the above and it's frankly heartening to watch BFG emerge as a framework with all due humility trying to right past wrongs as it were.

I was particularly taken by a related statement made elsewhere that "Features are the enemy of frameworks" or something to that effect. In my experience most frameworks evolve features faster than anything, quite in opposition to this axiom. I think this is because features are easy and largely fun to do. They also tend to give the framework developers an inflated sense of the framework's worth. However features must be documented and maintained, and thus this initial fun either leads to pain for developers, users or both. That, of course, assumes there are users besides the developers. It seems to me that a large number of frameworks are personal projects that are released with good (or perhaps grandiose) intentions, but never amount to much more than personal religions, if I may.

I think there are some other major pitfalls that can be illustrated handily by two of our favorite frameworks.

One would be the application that becomes a framework. This would of course be our old friend Zope2. Since frameworks are almost applications, it seems like this should not be too problematic. Technologically it probably isn't, you could just pull out some of the hardwired application policies and features and somehow make them pluggable. But the practice of developing an application is often done with a different mindset on reuse, and whatever apis exist are designed only with the convenience of the application in mind. Often expediency is the order of the day, because folks largely don't care how horribly factored an application is underneath, so long as the paint on the outside is nice and glossy. So the focus is on an end-user that is different from the end-user of a framework, and thus making it into a framework after the fact leads to a big impedance-mismatch. OTOH, application do have one very strong benefit, they do something useful already. So using an application-turned-framework to build an application that is largely similar to the original one should be a cake-walk.

Another framework pitfall is the meta-framework. I think we all know which one I mean ;^). This is the polar opposite of the application-turned-framework. This framework has never been an application, and cares little about such things. It is a jig for building tools, a hammer factory, or maybe even a tool for building a tool factory, or maybe...nobody knows. The cool thing about the meta-framework though is that smart people, with an unnatural grasp of the abstract, can build their own frameworks out of it, and those frameworks might even have a discernible goal. And maybe those frameworks can be leveraged by normal human-brained application developers, even.

I think for a framework to really succeed and stand the test of time, it should aim for the middle ground. A framework is not an application, no, but it should imply applications and make easy applications trivial compared to not using the framework. Ideally a framework should be made only after struggling for some time developing applications without it. As much as it can, a framework should avoid being a religion, or at least avoid the "one true way" mentality. I think two things help here. One is developing applications with the framework while it is being developed, "eating your own dogfood" as it were. The second is documenting it completely as you develop it. Nothing flushes out embarrassing api-smell like using the api and documenting it.

It seems to me that a framework ideally is a structural construct built on top of a suite of libraries. In an ideal world, none of these libraries depends on the framework and they stand on their ow. Also the use of libraries outside of those originally envisioned is not precluded and does not require tons of glue code and ceremony. Of course everything depending on what a "structural construct" is. I'm interested in others opinions on this. An specifically opinions on things like:

- What goes in the framework itself vs. the libraries? When do features wind up in the framework in practice?
- What is the relationship between the framework and libraries developed alongside it? What are the current best practices for packaging, building, etc?
- In practice, how reusable are libraries designed alongside frameworks? What lessons have been learned?


Eloquently stated Chris. From what I know about BFG, I would say you do a good job of following your own advice. I think you left off a few things that are helpful to framework developers.

Test all parts of your framework. If you don't know if it's tested, it's not tested. Coverage and now Branch Coverage are friendly tools, use them.

If someone's framework doesn't fit your head, but parts of it do, figure out what kind of common ground you can make with said framework, and make an effort to collaborate with them. A good framework ends up with a community following. Membership in multiple communities is usually mutually beneficial, bridging the gaps between communities can make the difference between your ideas succeeding, or flaring out.

I've seen this happen once already in my short OSS career. DBSprockets vs. Rum. Sprox(DBSprockets predecessor) now has some community support, while Rum, with it's wacky rule-dispatch back end is kind of living in squalor. Also, FormAlchemy is another framework in this domain, and probably has equal footing to sprox. If we had both gotten together at the beginning, we could probably have a larger combined following, but my olive branch was not accepted.

The great thing about OSS is that even when we cannot agree politically, the proper licenses allow us to take those parts of the code that are valuable to us and meld them to our own purposes. This is why I favor a more open license like MIT over more restrictive GPL, but please please please, don't make this thread about licensing.

building a framework and a career

chris is a poet.

"The problem that your framework solves should largely represent a career choice."

this one line did more to help me (finally) understood what distinguishes a framework from mundane applications than any other clue i've encountered - including being involved in the development of a few frameworks and more than a few applications.

it got me to think about inertial mass. a framework is all about systematic commitment to agreements - APIs - which constitute the intertial mass of a system. the bigger the framework gets, the harder it is to change its direction, and the further ahead you have to anticipate course corrections (where *did* that darn iceberg come from?!), etc. your effort will all be wasted if you can't pick a good course to start with, or be willing to start over once you get familiar enough with the domain to understand where you went wrong...

(hiya, casey!)