Designing for Others- Commercial API Design (NYC Code Camp)

  • 946 views
Uploaded on

 

More in: Technology
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
    Be the first to like this
No Downloads

Views

Total Views
946
On Slideshare
0
From Embeds
0
Number of Embeds
3

Actions

Shares
Downloads
7
Comments
0
Likes
0

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide
  • 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

Transcript

  • 1. Designing APIs for Others
    Real World Lessons About
    Commercial API Development
  • 2. Typical Programming Goals
    Minimize maintenance cost & risk
    Extensible / refactorable to new requirements
    Easy to read the source code
  • 3. 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
  • 4. How Users Discover
    Code Samples
    Very narrow, taken literally
    IntelliSense Driven Discovery
    See that they probably can do what they want to.
  • 5. IntelliSense Discovery Demo
  • 6. 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
  • 7. 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
  • 8. Inheritance Demo
  • 9. Inheritance
    Awkward IntelliSense
    Hardening Tricky
    Alternating viewpoints (External & Internal)
    Compromise Simplicity
    • Advanced User Cool Factor
    • 10. Customer Request Safety Net
  • Exceptions
    Thrown at very predictable points
    Use intrinsic types wherever they can fit
    Pick types that make sense from the outside
    Custom types are great for internal exceptions caught & re-thrown
  • 11. Hardening
    Event Pattern
    Property Transitions
    Inheritance
  • 12. Hardening Demo
  • 13. 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.
  • 14. Packaging
    Fewer Assemblies
    Runnable Sample Solution
    Clear Redistribution Requirements
    Xml Help, PDB if feasible
    Unit tests if available
  • 15. Common Mistakes
    Users aren’t as smart as you
    Domain knowledge
    Coding capability
    Internal / Tribe Language
    Inconsistent
    Framework + API + Experience
    Single Minded
  • 16. Most Common Mistake
    You must have at least two, independent external teams use your API while it’s still changeable
  • 17. Additional Information
    Book
    Framework Design Guidelines by Krzysztof Cwalina
    Websites
    www.GibraltarSoftware.com
    www.eSymmetrix.com
    Follow Up
    Kendall.Miller@eSymmetrix.com
    Twitter: kendallmiller