Designing for Others- Commercial API Design (NYC Code Camp)Presentation Transcript
Designing APIs for Others Real World Lessons About Commercial API Development
Typical Programming Goals Minimize maintenance cost & risk Extensible / refactorable to new requirements Easy to read the source code
Commercial API Goals Other people use your library and like it. Short First Reference -> First Wow Digestible, iterative discovery Easy Things are Easy, Hard Things are Possible
How Users Discover Code Samples Very narrow, taken literally IntelliSense Driven Discovery See that they probably can do what they want to.
IntelliSense Discovery Demo
Design Priorities Discovery through your fingers Where possible can’t be misused Don’t show what they don’t need Advanced features in advanced ways Hard Shell Designer->Compile->Runtime
Key Implementation Method Always outside in – terms, flow, exception types. Reads like the outline of a book Fewer, Flatter Sample Driven Development Samples are your test cases Digestible chunks of WHY Consistency
FxCop / VS Code Analysis Catches all manner of subtle things You can ignore its advice – but know why Use of generic event handlers Exposing generic collections Samples too – don’t require users to break the rules FxCop free in the Windows SDK, VS Code Analysis in Pro & higher editions.
Packaging Fewer Assemblies Runnable Sample Solution Clear Redistribution Requirements Xml Help, PDB if feasible Unit tests if available
Common Mistakes Users aren’t as smart as you Domain knowledge Coding capability Internal / Tribe Language Inconsistent Framework + API + Experience Single Minded
Most Common Mistake You must have at least two, independent external teams use your API while it’s still changeable
Additional Information Book Framework Design Guidelines by Krzysztof Cwalina Websites www.GibraltarSoftware.com www.eSymmetrix.com Follow Up Kendall.Miller@eSymmetrix.com Twitter: kendallmiller