Gem API design

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

Emily [email protected]@EmStolfo

Talk to me about the Ruby driver :)