Ccontinuing in our weekly blog post series that highlights a few of the new additions to the Framework Design Guidelines 2nd edition.. This annotation is found in Chapter 2: Framework Design Fundamentals. Joe and Chris nail the core things.
As software developers, we enjoy creating fun and powerful new capabilities, and sharing them with other developers. That’s one of the reasons API design is so enjoyable. But it’s also incredibly difficult to step back and objectively assess whether some new capability that you’re particularly passionate about has utility in the real world. Using scenarios is the best way I know of to identify the need for and ideal usage of new capabilities. Developing scenarios is in fact incredibly hard, for good reason: It requires a unique combination of technical skill and customer understanding. When you’re finished, you could make a series of decisions based only on gut feel and intuition, and perhaps deliver some useful APIs, but the risk that you will make a decision you will later regret is far greater. When in doubt, it’s best to leave a feature out and decide to add it later when a compelling need is better understood.
Each developer has his or her own methodology, and although there isn’t anything fundamentally wrong with using other modeling approaches, the problem generally is the output. Starting by writing the code you want a developer to write is almost always the best approach—think of it as a form of test-driven development. You write the perfect code and then work backwards to figure out the object model that you would want.