Building a Ruby Library: The Parts No One Talks About

Building a Ruby Library: The Parts No One Talks About

2828f28fb012308a7786eee83b8293c5?s=128

Mitchell Hashimoto

June 02, 2012
Tweet

Transcript

  1. Building a Ruby Library The Parts No One Talks About

  2. Mitchell Hashimoto @mitchellh

  3. None
  4. And a thanks to my employer, Kiip, for being supportive

    of my open source endeavors. We’re hiring! http:/ /kiip.me
  5. Big shout out to Engine Yard for sponsoring my open

    source work and supporting me in helping the Ruby community.
  6. WARNING! OPINIONS AHEAD This talk has many opinions throughout. I

    try to back up my opinions with some evidence but of course there will be differing thoughts. My opinions are based on over two years of maintaining relatively popular Ruby libraries, as well as being a full-time Ruby dev for over five years.
  7. A Good Ruby Library? What makes a good Ruby library?

    Most people think “easy to use” or “simple” or “clean API.” But there is a lot more going on that is equally important.
  8. ✓ Intuitive API Clearly, API matters. Most devs jump straight

    to code samples for libraries, and a clean API will be the first sell.
  9. But... The Other Parts Intuitive API everyone always gets. But

    there are a LOT of other parts to a good Ruby library. Let’s go over them quickly, then in more detail later.
  10. ✓ Configurable Almost all libraries have tunable elements. Exposing those

    tunable elements in a predictable way is important to give your library the most power, while retaining its simplicity.
  11. ✓ Logged Easily overlooked, when a library DOESNT work, users

    of a library would like to know whats going on without diving straight into the source code. Properly structured log messages are a godsend.
  12. ✓ Exceptions If I’m using an HTTP library and make

    a request, I don’t want to see a SocketError pop up. I didn’t make a socket, how did I error? Libraries should catch their exceptions, wrap them in their own, and expose them in a documented way. More on this later.
  13. ✓ Documentation The biggest problem with open source. A library

    needs documentation.
  14. ✓ Support Users of your library need a way to

    get support if they need it.
  15. The Boring Parts So these are the boring parts. No

    one talks about them. No one talks about them.
  16. A Good Ruby Library. All of these things put together

    make a FANTASTIC library. Whole is greater than the sum of its parts.
  17. 1. Intuitive API

  18. Idiomatic Ruby * Don’t do anything crazy, just stick with

    the norms. * Ruby has been around for a long time now, we’ve got our conventions. * Helps people pick it up faster. * Gives users that “it just feels right” feeling. Don’t try to be cool. I’m not going to spend much time on this section because this is generally the part that people get right, because they’re used to working with Ruby already and this is what they focus on. Plus, during the talk I’m super crunched for time, so I had to move on.
  19. 2. Configurable

  20. Plain old Ruby * Don’t try something fancy, configuration should

    be non-magical and straightforward. * Use plain Ruby (APIs), or maybe JSON/YAML for tools. Config should have NO MAGIC.
  21. Central configuration * Don’t try something fancy, configuration should be

    non-magical and straightforward. * Use plain Ruby (APIs), or maybe JSON/YAML for tools. Keep it in one place.
  22. 1 require "mylib" 2 3 MyLib.configure do |config| 4 config.setting

    = "value" 5 config.enable_something! 6 end * Central configuration * Plain old ruby object (`config`) Central Configuration
  23. Instance configuration via initializers and option hashes * Don’t try

    something fancy, configuration should be non-magical and straightforward. * Use plain Ruby (APIs), or maybe JSON/YAML for tools. Idiomatic, well understood.
  24. 1 require "mylib" 2 3 obj = MyLib.new(:setting => "value")

    4 obj.setting = "value2" * Use normal constructors and option hashes for instance-level configuration. * Very idiomatic, very clear. Instance Configuration
  25. 3. Logging

  26. Ruby’s stdlib Logger is GARBAGE. * Lack of namespacing. *

    Only goes to IO objects Basically renders logging useless in my opinion.
  27. Use log4r * Namespacing * Yeah it’s a dependency for

    your gem, but well worth it. http://log4r.rubyforge.org/
  28. Usage: Your API 1 log = Log4r::Logger.new("mylib::connection") 2 log.debug("debug!") 3

    log.info("information") This is the API that you would use as a developer of a library. Simple enough.
  29. Usage: User API 1 log = Log4r::Logger.new("mylib") 2 log.outputters =

    3 Log4r::Outputter.stderr 4 log.level = Log4r::INFO This is what the user of your library would have to do to enable logging for your library. Super easy, predictable.
  30. Don’t: • Print to stdout/stderr • Rely on “debug” config

    option • Use something custom * stdout/stderr: Tempting, but extremely annoying and can cause crashes if pipe is closed. * “debug” option is fine, but don’t require it. Sometimes I want debug logging, but not other debug behavior. * log4r may not be the best, but the last thing we need is more fragmentation.
  31. 4. Exceptions

  32. Without Exceptions: Abstraction Leakage * Lack of properly handling exceptions

    causes abstraction leakage. * Goal: Catch any possible exceptions, wrap and expose using your own.
  33. Abstraction Leakage 1 require "twitter" 2 3 Twitter.socialize! Example: Let’s

    say you’re doing something with Twitter. It doesn’t matter what, it’s just important to know that there is network activity going on.
  34. Bad: Result ! ruby app.rb app.rb:in `initialize': unknown socket domain:

    twitter.com (SocketError) ! from app.rb:in `new' ! from app.rb:in `<main>' This is the API that you would use as a developer of a library. Simple enough.
  35. Single Parent Exception Class * Allows a “catch all” for

    a specific library very easily. * Can find all children classes easily. * Inherit from StandardError, so that catch-alls still work on that.
  36. Single Parent Class 1 require "twitter" 2 3 begin 4

    Twitter.socialize! 5 rescue Twitter::Error 6 # Twitter is always down so 7 # I stopped caring. 8 end A single parent class makes it easy to catch-all in a specific library, such as this case.
  37. Many Subclasses Be descriptive! * Don’t be afraid, make a

    lot! The user can always “catch all” * Make the name descriptive, makes it a lot easier to read code.
  38. Descriptive Subclasses ! ruby app.rb app.rb:in `initialize': Failed to connect

    to twitter (Twitter::ConnectionError) ! from app.rb:in `new' ! from app.rb:in `<main>' With descriptive, specific error classes, its easy to see what is going on and to catch that specific example.
  39. Use Standard Exceptions When it makes sense. * Don’t reinvent

    the wheel: FooNotEnoughArguments, just use ArgumentError There aren’t many available, but the basics are good.
  40. 5. Documentation * Two kinds: API docs (libraries) and usage

    docs (tools) * Both should be kept in the same repo as the code, ideally. * Write it AS YOU CODE. Same as tests.
  41. Write it from the beginning. * Its easy to push

    off docs until the end so your lib isn’t changing much anymore, but documentation is SO BORING that you’ll end up hating yourself. * Write it as you go (like tests). If the library changes, then you’ll have to change docs, so there is more work, but at least you’ll have the docs at the end. * Example: Vagrant 0.1 docs pushed off until the end, took me 2 weeks to write them. Really burned me out. More work, but less pain.
  42. Keep it with the code. * Docs should be in

    the same repo as the code. * Use a branch, won’t ever be merged into master, so clean it and just keep it going. * Makes it easy to contribute. (Pull requests!) * Can see “point-in-time” documentation for specific versions
  43. API: Use YARD * API docs, use YARD * Similar

    to RDoc/JavaDoc, so its familiar. * Generates pretty HTML, PDFs. * You automatically get generated docs from rubydoc.info http://yardoc.org
  44. Other: Markdown + Jekyll * For other docs, use plain

    old markdown, but try to fit it into a Jekyll-powered site. * Two birds, one stone: - Readable from the source. - Able to generate a pretty website. Readable + Website!
  45. 6. Support

  46. Unsupported code is not “open source” * If I don’t

    see support, I either don’t use the project or I use the code as reference to implement something myself. It’s just reference material.
  47. Support doesn’t have to equal work Providing support doesn’t mean

    you need to work much harder. Its simply more important to provide the opportunity for support.
  48. Users just need something. Support just needs to be SOMETHING.

    IRC, mailing list, issues, etc.
  49. A Great Ruby Library. With all these things put together,

    you don’t get a good Ruby library, you get a _great_ Ruby library. From learning about your library to developing with it to maintaining it, everyone will thank you.
  50. Thanks!