Your biggest competition is the user’s belief in the difficulty of solving the problem.
Misuse prevention: Thread safety, order of operations, types, null behaviorsDon’t show what they don’t need: Internal, hide on interfaces, veneer the APIHard Shell: Don’t trust any code around or above you.
Consistent with the framework and itself, then with likely customer experience.
Prefer to have the fewest assemblies you can, and their names are part of their interface.Use different names for valid combinations – like .NET 20 and .NET 40. Have a reason for the CUSTOMER that you broke apart
Your job is to hide the complexity of your domain from users, not show how smart you areQuality is tightly related to how well it blends into the enviornmentYour preferences aren’t their preferences – configuration, designer or code
Designing APIs for Others
Designing APIs for Others<br />Real World Lessons About <br />Commercial API Development<br />
Typical Programming Goals<br />Minimize maintenance cost & risk<br />Extensible / refactorable to new requirements<br />Easy to read the source code<br />
Commercial API Goals<br />Other people use your library and like it.<br />Short First Reference -> First Wow<br />Digestible, iterative discovery<br />Easy Things are Easy, Hard Things are Possible<br />
How Users Discover<br />Code Samples<br />Very narrow, taken literally<br />IntelliSense Driven Discovery<br />See that they probably can do what they want to.<br />
Design Priorities<br />Discovery through your fingers<br />Where possible can’t be misused<br />Don’t show what they don’t need<br />Advanced features in advanced ways<br />Hard Shell<br />Designer->Compile->Runtime<br />
Key Implementation Method<br />Always outside in – terms, flow, exception types.<br />Reads like the outline of a book<br />Fewer, Flatter<br />Sample Driven Development<br />Samples are your test cases<br />Digestible chunks of WHY<br />Consistency<br />
Customer Request Safety Net</li></li></ul><li>Exceptions<br />Thrown at very predictable points<br />Use intrinsic types wherever they can fit<br />Pick types that make sense from the outside<br />Custom types are great for internal exceptions caught & re-thrown<br />
FxCop<br />Catches all manner of subtle things<br />You can ignore its advice – but know why<br />Use of generic event handlers<br />Exposing generic collections<br />Samples too – don’t require users to break the rules<br />
Packaging<br />Fewer Assemblies<br />Runnable Sample Solution<br />Clear Redistribution Requirements<br />Xml Help, PDB if feasible<br />Unit tests if available<br />
Common Mistakes<br />Users aren’t as smart as you<br />Domain knowledge<br />Coding capability<br />Internal / Tribe Language<br />Inconsistent<br />Framework + API + Experience<br />Single Minded<br />
Most Common Mistake<br />You must have at least two, independent external teams use your API while it’s still changeable<br />
Additional Information<br />Book<br />Framework Design Guidelines by Krzysztof Cwalina<br />Websites<br />www.GibraltarSoftware.com<br />www.eSymmetrix.com<br />Follow Up<br />Kendall.Miller@eSymmetrix.com<br />Twitter: kendallmiller<br />