Gem API design
for authors
(and users)

Emily Stolfo
Ruby Engineer at
@EmStolfo

, Adjunct Faculty at Columbia
Many of us
have become
gem authors.
(whether we like it or not)
Our code served a
browser and a
mouse.
Now our code serves
other developers.
Is it just me, or does ____ seem like a
poorly designed piece of software; lots
of magic, poor OOP design, poor
documentat...
gem API design is

UX design
The UX Fund
experiment
Great user
experience is
directly reflected
in stock price.
RubyGems
Developer Experience
(DX) team
Drivers
Docs
Tools
gem API design is

UX design
USERS
Know your users.*

* open source users or your colleagues
Listen in.
Read blogs.
Use twitter.
Talk to users.
Give presentations.
Establish trust.
USE
SEMANTIC
VERSIONING
Involve

super users.
UX DESIGN
CONCEPTS
Consistency
Simplicity
Mapping
Consistency

Simplicity

Mapping
Consistency

Simplicity

Mapping
Consistency

Simplicity

Mapping
3 Consistency Considerations
4 Simplicity Suggestions
5 Mapping Mantras
Consistency
Considerations
1. Consider
consistent naming.
2. Consider
consistent style.
3. Consider
consistent behavior.
Simplicity
Suggestions
1. Give classes a
single responsibility.
2. Hide
implementation
details.
attr_reader :name, :connection
...
protected
...
private
...
3. Be frugal with
helpers.
Index creation

X

@posts.text_index(‘title’)

@posts.create_index({ ‘title’ => Mongo::TEXT })
4. Design your API
first.
new driver “fluent API”

X

@orders.find_and_modify(
:query => {},
:new => true,
:update => {:$set =>
{:processed => true}...
Mapping
Mantras
1. Monkey-patching
is mean.
refinements
refine String do
...
end
2. Side effects are
surprising.
Mutating opts

X

def map_reduce(map, reduce, opts={})
...
raw = opts.delete(:raw)
...

def map_reduce(map, reduce, opts={...
3. Requiring
method chaining
is impolite.
X

@client.pool_manager.primary_pool

@client.primary
4. Informative error
messages are
imperative.
mongoid
5. Documentation
without hesitation.
# inline comments
Documentation tools
README.md
Getting started
http://code.dblock.org/your-first-ruby-gem
Think like a
UX designer.
Get social.
© JEG2
Talk to me about
the Ruby driver :)
Emily Stolfo
emily@mongodb.com
@EmStolfo
Gem API design
Gem API design
Upcoming SlideShare
Loading in …5
×

Gem API design

2,515 views

Published on

API design for gem authors (and users)

Ruby applications are becoming more complex and unwieldy (think MonoRails). An increasing number of us are trying to address this by separating our apps into gems without knowing best practices on how to write APIs or how to manage dependencies and versioning. The discussion we often have around good APIs should not stop with Ruby OO design, but should also consider the public APIs of gems.

This talk is intended for gem authors and users. It will share though many practical examples using the Ruby driver to MongoDB 1) Principles of good gem API design, 2) How to make your gem API optimal for users and how to best use the API of a gem, 3) Guidelines for introducing and anticipating gem API changes and managing dependencies.

Published in: Technology, Education
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
2,515
On SlideShare
0
From Embeds
0
Number of Embeds
217
Actions
Shares
0
Downloads
6
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Gem API design

  1. 1. Gem API design for authors (and users) Emily Stolfo Ruby Engineer at @EmStolfo , Adjunct Faculty at Columbia
  2. 2. Many of us have become gem authors. (whether we like it or not)
  3. 3. Our code served a browser and a mouse.
  4. 4. Now our code serves other developers.
  5. 5. Is it just me, or does ____ seem like a poorly designed piece of software; lots of magic, poor OOP design, poor documentation, etc.? I appreciate the contribution to open source, though.
  6. 6. gem API design is UX design
  7. 7. The UX Fund experiment
  8. 8. Great user experience is directly reflected in stock price.
  9. 9. RubyGems
  10. 10. Developer Experience (DX) team Drivers Docs Tools
  11. 11. gem API design is UX design
  12. 12. USERS
  13. 13. Know your users.* * open source users or your colleagues
  14. 14. Listen in.
  15. 15. Read blogs. Use twitter. Talk to users. Give presentations.
  16. 16. Establish trust.
  17. 17. USE SEMANTIC VERSIONING
  18. 18. Involve super users.
  19. 19. UX DESIGN CONCEPTS
  20. 20. Consistency Simplicity Mapping
  21. 21. Consistency Simplicity Mapping
  22. 22. Consistency Simplicity Mapping
  23. 23. Consistency Simplicity Mapping
  24. 24. 3 Consistency Considerations 4 Simplicity Suggestions 5 Mapping Mantras
  25. 25. Consistency Considerations
  26. 26. 1. Consider consistent naming.
  27. 27. 2. Consider consistent style.
  28. 28. 3. Consider consistent behavior.
  29. 29. Simplicity Suggestions
  30. 30. 1. Give classes a single responsibility.
  31. 31. 2. Hide implementation details.
  32. 32. attr_reader :name, :connection ... protected ... private ...
  33. 33. 3. Be frugal with helpers.
  34. 34. Index creation X @posts.text_index(‘title’) @posts.create_index({ ‘title’ => Mongo::TEXT })
  35. 35. 4. Design your API first.
  36. 36. new driver “fluent API” X @orders.find_and_modify( :query => {}, :new => true, :update => {:$set => {:processed => true}) @orders.find({}). update_one_then_get({:$set => {:processed => true})
  37. 37. Mapping Mantras
  38. 38. 1. Monkey-patching is mean.
  39. 39. refinements refine String do ... end
  40. 40. 2. Side effects are surprising.
  41. 41. Mutating opts X def map_reduce(map, reduce, opts={}) ... raw = opts.delete(:raw) ... def map_reduce(map, reduce, opts={}) opts = opts.dup raw = opts.delete(:raw) ...
  42. 42. 3. Requiring method chaining is impolite.
  43. 43. X @client.pool_manager.primary_pool @client.primary
  44. 44. 4. Informative error messages are imperative.
  45. 45. mongoid
  46. 46. 5. Documentation without hesitation.
  47. 47. # inline comments
  48. 48. Documentation tools
  49. 49. README.md
  50. 50. Getting started http://code.dblock.org/your-first-ruby-gem
  51. 51. Think like a UX designer.
  52. 52. Get social. © JEG2
  53. 53. Talk to me about the Ruby driver :) Emily Stolfo emily@mongodb.com @EmStolfo

×