Hashrocket Lunch & Learn #2 Avdi Grimm 2012-04-19 

Building Libraries that Don’t Suck Distribution Coding API Design Error API Design 

Distribution 

Limit dependencies Yes, ActiveSupport is the bee’s knees . . . but it may break someone’s codebase 

Semantic Versioning Patch versions: fix defects. Minor versions: add features; never change existing (correct) behavior. Major version: break backwards compatibility Make the tiddly-waka (~>) count for something! 

Don’t name it after a pattern That’s just confusing. 

Coding 

No monkey patching! (Unless that’s the purpose of the library) 

No classes named “Base” Don’t make grepping any harder than it needs to be. Identify the concept, and name it. (ActiveRecord::Record, anyone?) Exceptions: Libraries involving baseball Libraries about base jumping Libraries concerned with Swedish 90s pop group Ace of Base 

Don’t eat client exceptions module SWS def with_sandwich # ... yield sandwich rescue => e # OM NOM NOM EXCEPTIONS! nil end end 

Don’t eat client exceptions # Meanwhile, in client code SWS.with_sandwich do # ... some_method_that_raises_a_runtime_error # ... end 

API design 

Block-style configuration SWS.configure do |config| conf.selleck_shirtless = true conf.sandwich_type = :baloney conf.waterfall_height *= 2 end 

Block-style configuration Code-as-config for ultimate flexibility Discoverable: default values can be queried. A convenient point to add validations Can be called more than once 

Top-level Facade # Instead of: SWS::Sandwich.new(...) # Try: SWS.new_sandwich(...) 

Top-level Facade Top-level API acts as a reference Doesn’t tie client code to the structure of your library Gives you more leeway to move things around internally Or proliferate classes 

Error API 

Exception Classes Logic Error: Library has a defect. Client Error: Client mis-used the library. Transient Failure: Some external dependency isn’t working right now. 

Exception Tagging with Modules module SWS::Error; end # ... def upload_selleck_to_waterfall # ... rescue HTTPError => e e.extend(SWS::Error) raise end 

Exception Tagging with Modules # Client code interested in HTTP errors def foo upload_selleck_to_waterfall rescue HTTPError => e log_http_error(e) end 

Exception Tagging with Modules # Client code concerned with SWS errors def foo upload_selleck_to_waterfall rescue SWS::Error # ignore SWS errors end 

No-raise API request.on_complete do |response| if response.success? # hell yeah elsif response.timed_out? # aw hell no log( "got a time out" ) elsif response.code == 0 # Could not get an http response log(response.curl_error_message) else # Received a non-successful http response. log( "request failed: " + response.code.to_s) end end 

Tiered Architecture For wrapping services / libraries Layer 1: Thinnest possible wrapper Typically procedural Stateless Minimal “magic” Layer 2: Object model Stateful 

Tiered Architecture Evolution Layer 1: Thinnest possible wrapper Layer 2: Glue Layer 3: Object model 

Your Turn