Embed Size (px)
Citation preview
Gem API design for authors
Emily StolfoRuby Engineer at , Adjunct Faculty at Columbia@EmStolfo
(and users)
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 documentation, etc.? I appreciate the contribution to open source, though.
gem API design is
UX design
The UX Fund experiment
Great user experience is
directly reflected in stock price.
RubyGems
Developer Experience (DX) team
DriversDocs
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
ConsistencySimplicityMapping
Consistency MappingSimplicity
Simplicity MappingConsistency
MappingSimplicityConsistency
3 Consistency Considerations
4 Simplicity Suggestions
5 Mapping Mantras
Consistency Considerations
1. Consider consistent naming.
2. Consider consistent style.
3. Consider consistent behavior.
SimplicitySuggestions
1. Give classes a single responsibility.
2. Hide implementation details.
attr_reader :name, :connection
...
protected
...
private
...
3. Be frugal with helpers.
Index creation
@posts.text_index(‘title’)
@posts.create_index({ ‘title’ => Mongo::TEXT })
X
4. Design your API first.
new driver “fluent API”
@orders.find_and_modify( :query => {}, :new => true, :update => {:$set => {:processed => true})
@orders.find({}). update_one_then_get({:$set => {:processed => true})
X
Mapping Mantras
1. Monkey-patching is mean.
refine String do ... end
refinements
2. Side effects are surprising.
Mutating opts def map_reduce(map, reduce, opts={}) ... raw = opts.delete(:raw) ...
def map_reduce(map, reduce, opts={}) opts = opts.dup raw = opts.delete(:raw) ...
X
3. Requiring method chaining is impolite.
@client.pool_manager.primary_pool
@client.primary
X
4. Informative error messages are imperative.
mongoid
5. Documentation without hesitation.
# inline comments
Documentation tools
README.md
Getting startedhttp://code.dblock.org/your-first-ruby-gem
Think like a UX designer.
Get social.© JEG2
