Ruby Best Practices

James will be right back after these interruptions

james.britt@gmail.com (James Britt) — Sun, 30 Aug 2009 13:00:00 +0000

James will be right back after these interruptions

How many times has this happened to you?

[WAY-TOO-LOUD TV VOICE]: You’re working on some code, making good progress, solving a particular issue, when Oh No!,
you’ve run into a new bug. Now what?

You could open a browser, go to your issue tracker, and open a ticket. But that could take several minutes!

Your train of thought would be derailed, code momentum lost, and time wasted! But you can’t just let that bug slide away! Don’t you wish there was an easier way to handle this?

As far as I know there have been no late-night TV commercials selling solutions to software developers, but there are times we could use them. The problem of staying focused on one task, while not ignoring others, is a real one, at least for me, and I suspect many others.

Here’s what happens: You pick a bug to fix or feature to add, and set out to complete it. Almost inevitably, though, you encounter other issues or interests. If it looks to be minor, it’s tempting to fix it right then. Sometimes this is trivial; a typo in the UI text in the file you’re working on. These are the cases where even adding a FIXME or TODO to the code would be about as much work as just fixing the problem.

Other times, though, it’s obvious that this new concern will take a bit of time. Or, maybe worse, there’s no simple way to quickly judge how much work would be needed. Dropping what you’re doing to fix something else isn’t a recommended practice. Given that each task is prone to uncover a new task, you’re doomed from the start to never finish anything.

That leaves two (admittedly broad) options. One is to ignore everything that isn’t immediately related to the immediate task. The other is to stop what you’re doing and make a note of the problem. But how long is that going to take?

Now watch this!

Lately I’ve been interested in focus and attention. Like many people my ability to focus often varies. For tasks that don’t have an intrinsic lure (e.g. bug fixing) I work best if I stick to well-defined tasks over specific durations. (This is an approach sometimes referred to as time boxing. Some formal examples are the Pomodoro Technique and the Autofocus System).

An important aspect is to really spend that time doing that specific task. If it leads to assorted sub-tasks, it matters how much time those things take, since time is limited. If necessary digressions take too long, the whole “do one thing” plan falls apart, as does one’s focus.

So now we have two problems. One, the code distraction that just appeared, and two, the need for a way to quickly and effectively record it. Here’s what I’ve been doing about that second one, which leads to solving the first one.

I first started looking into the idea of rapid notation when I was working a contract job that needed some detailed time tracking. After spending two hours adding what seemed like a simple feature to a Java Web app I wanted to be able to look a back a see just where the time went.

I started by using a plain text file. Every so often, when I found myself doing something that didn’t seem to be directly adding to a solution (for example, rebooting the app server to fix JVM out-of-memory issues) I made a note.

It worked OK, but it was a bit slow. There was a lot of friction on opening the file, adding text, and saving it. Even leaving the file open all the time was not helpful enough. As I usually work at the command line I wrote a small Ruby script to let me write my notes right from the terminal.


    #!/usr/bin/env ruby

    @data_file = "/home/james/data/_at-today-please.txt" 

    def ts; Time.now.to_s; end

    def edit
      IO.popen "gvim #{@data_file} & "
    end

    def add
      msg = ARGV.join( ' ' ).to_s.strip
      File.open(@data_file, "a") do |f|
        f.print "--- #{ts}:\n\t#{msg}\n\n\n"
      end
    end

    ARGV.empty? ? edit : add

I’m not making any claims for this code other than follows the principal of WFJ: Works for James. I have it in a file at ~/bin/@; adding a short note is about as simple as it gets. If I need to add something complex (or something that just doesn’t play well at the command line), I pass no arguments and edit the file directly.

It’s flawed, of course. Depending on the shell, different chracters (quote marks, for example) can throw things off. But it works good enough for quick time-stamped notes.

But wait, there’s more!

Some time after this hack I found myself working with Trac. It does a good job of coordinating source code, issues, project planning, and assorted other goodies. Entering bugs, though, was a drag. The Web UI meant entering text in multiple fields and selecting values from a few dropdown lists. Once again, to keep from getting too distracted while developing I wrote some code to post tickets from the command line. The project was called Tracula (because the key to any project is a clever punny name) and helped my development process by removing some of the friction of tracking issues uncovered during development. Usage hit some snags when different versions of Trac required somewhat more gnarly means of athenticating HTTP posts, while my use of Trac dropped in favor of other project management tools.

Nonetheless, the general idea stayed with me, and when picking any tool I look to see if there’s a simple HTTP interface that allows for automation and custom command-line driven clients.

I now have several projects on GitHub.com, which has become much like a hosted Trac, but with more ass-kickery. Each repo can have an issue tracker, and I’ve just started using it for my Rhesus project.

Rhesus is yet another WFJ tool that has been evolving as I use it. I had been making notes about the code in various places when I realized there was an actual bug tracker available. I added a few issues, and immediately wondered if there was an API for this. And there is (thanks, Engine Yard!).

With Tracula there were three key options: fetch a list of open tickets; post a single new ticket; do a batch post of mulitple tickets. How to do these with the GitHub API? Well, fetching tickets is really easy, since there’s no need for any authentication. If you have curl or wget installed, it’s a just a well-crafted URL:

    http://github.com/api/v2/json/issues/list/Neurogami/rhesus/open

will give you a list of open Rhesus issues. Very slick, but since the results are a JSON string, maybe not the easiest thing to read. You can change that to XML or YAML if you like, but for better control, how about using some Ruby to slurp it in and present it in a more refined manner?

And if you call RIGHT NOW …

A basic approach to showing the current set of open issues might be: make a call to the GitHub API; parse the results into some useful Ruby structure; selectively show the details to avoid overcrowding the screen. One thing you need to consider, though, is just how often will the list of issues change relative to the number of times you want to see it. In my case, I’ll likely want to see the list way more often than it will change. To make life easier both for me and for GitHub, I want my code to cache the list of issues and render that cache by default. I’m also going to make this a Rake task, and I’ll allow for a parameter to indicate that the cache should be updated.


  namespace :issues do
    desc 'Open issues'
    task :open do
      paged_issues ENV['GH_NO_CACHE']
    end
  end

The page_issues method will grab the set of issues and render them one by one:


  def ___
    warn "\n" + '_' * 30
  end

  def paged_issues no_cache = false
    ARGV.clear # Otherwise the call to gets will immediately find input
    warn "Hit <enter> after each issue to see the next one."
    issues(no_cache).each do |issue|
      ___
      warn "Title: #{issue['title']}"
      warn "Details: \n#{issue['body']}"
      ___
      gets
    end
    warn "\nThat's it!"
  end

The issues method will either pull from the cache or fetch anew from GitHub


    def issues no_cache = false
      issues_cache = 'issues.yaml'
      if no_cache || !File.exist?(issues_cache)
         warn "Reloading issues from GitHub ..."
         File.open( issues_cache, 'w'){ |f| f.puts get_issues }
      end
      YAML.load(IO.read(issues_cache))['issues']
    end

This allows for

rake issues:open

and

rake issues:open  GH_NO_CHACHE=true

Operators are standing by!

What about adding a new issue? The docs say that an authorized POST is needed. And what’s an authorized POST? It’s an HTPP POST with parameters for your user name (login) and your authorization token (token). The latter may be found on your GitHub account page.


     namespace :issues do
      # ...
      desc 'Create a new issue'
      task :create do
        issue_details = ENV['DETAILS'].to_s.strip
        if issue_details.empty?
          warn "No issue details!"
        else
          title, body =  issue_details.split(' -- ', 2)
          create_issue  title, body 
        end
      end
    
     # ...
     end

Rake is not the most friendly when it comes to passing arguments, so to (somewhat) simplify things I decided to use one parameter that employed a delimiter to set off the issue title and body. The code that does the actual ticket creation is oblivious to this, and could easily be used in a regular Ruby app. The choice of making something a Rake task or a stand-alone executable depends on how you expect to use it. With Rake, it’s easy to get a reminder of what tasks are available using rake -T. The downside is that argument handling is not so nice.

(Were this more than demo code, though, I would ultimately make the core code a library so that having both a Rake task and a standalone app would be equally easy. And, in fact, some folks have been working on GitHub API Ruby libraries.)

Doing a POST is a bit more complex than just reading from a URL, but no big deal:


      def create_issue title, body
        require 'net/http'
        require 'uri'

        token = ENV['GH_AUTH_TOKEN']
        url = 'http://github.com/api/v2/yaml/issues/open/Neurogami/rhesus'
        res = Net::HTTP.post_form(URI.parse(url),
                                  {'title'=> title, 
                                      'body' => body,
                                      'login' => 'Neurogami',
                                       'token'=> token }
                                 )
        warn res.body

      end

Note that the code pulls the authentication token from an environment variable. That’s done to avoid having to embed it in the code or some config file that may inadvertently reach the wrong eyes.

As for bulk posting of issues, well, better add a ticket for that.

But that’s not all; you’ll also get this!

I must confess that I’ve been writing the code as I wrote this post. It’s an amazingly useful way to get some code written.

I thought about the whole “Oh, if you were really doing this right, you’d make this a library” thing, and, well, I made this a library thing.

You can get the code here: http://github.com/Neurogami/ghissues/tree/master

It’s basically the above code, with some provisions for reading a local config file that defines the repo, repo owner, and a file for saving a cache of the repo issues. (A down-side of coding-for-content is that certain niceties, like docs and tests, may fall by the wayside. The code, however, is pretty simple.)

Re-doing the Rake tasks using this gem is left as an exercise for the reader.

Don’t wait; act now!

I’ve written a few other apps along these lines. One lets me add items to my list at Todoist.com. I can even set reminders to pester me to do something later. Very handy; the improved speed in setting a reminder or adding a new bug ticket is well worth the time spent coding up such tools. There are numerous existing apps out there for things like this as well. (Check out this thread on Hacker News.). See if one doesn’t help you do more with less friction.

But if you can’t find one that really works for you, consider writing your own. It’s not hard, and there’s a real payoff in having something that fits your style and keeps you moving.

"And your Mom, too." Ruby-talk best practices.

james.britt@gmail.com (James Britt) — Wed, 10 Jun 2009 21:59:00 +0000

Mailing lists (and bulletin boards and forums and so on) are important parts of becoming a better developers. Even the best programmers need help, and a mailing list such as ruby-talk (or the Usenet version, comp.lang.ruby) is the traditional place to go.

Mailing lists are also a good place to get better at your craft; watch the list, and try to answer questions. Think of it as pop quizzes at Ruby U.

Mailing lists are also good place to toss out ideas, conjecture about the future of Ruby, and have general Ruby-related discussions.

There are, however, right and wrong ways to go about this. The canonical source for what is termed “Netiquette” is Internet Engineering Task Force RFC 1855.

You should read it. However, it’s somewhat lengthy, and some aspects dated. Here, I’d like to focus on a few key items as they relate to Ruby and ruby-talk.

RFC 1855 in a Nutshell

For the tl;dr crowd: Don’t be a complete jerk.

I can’t suggest not being any kind of jerk at all in anyway, because it’s impossible. The Web is a big place. No matter what you say or do, there is every chance that someone, somewhere, will take offence, or think you stupid, or in some way take you the wrong way.

There’s not much you can do about that, but you can be mindful of some general decency. For Rubyists, the key is MINASWAN: Matz is nice, and so we are nice.

This doesn’t mean not being critical, or not pointing out mistakes, or not offering bold opinions. It means directing your comments to ideas, not personalities. It means understanding that being wrong doesn’t make a person bad or stupid, just wrong. And being wrong on one thing does make make a person wrong on everything.

It also means not jumping down someone’s throat because their sense of humor doesn’t jibe with yours.

Discussions on ruby-talk can get heated, and the temptation can be strong to let loose with snark and bile. Typically it ends up counter-productive, but it’s understandable.

Threads would likely be much less fun if everything was sanitized. However, the line needs to be drawn at personal attacks and comments.

Ideas can be foolish; people are not fools simply for expressing a foolish idea. Code can be bad; people are not bad for writing such code.

It’s About Code and Ideas

Few people post to ruby-talk to make personal attacks (barring trolls, who should never ever be fed), but it happens. Before letting loose that little bit of one-upmanship, consider what you are really trying to accomplish. If the goal is hurt someone: Please remember MINASWAN. If you cannot, then please go elsewhere.

If the goal is to see Ruby improve, or to express an idea, or to get help with some code, or to offer help, then stop and think.

That brief moment of satisfaction will fade, and you will have failed in your larger intent.

Ruby-talk has a tradition of being very welcoming to newcomers, with many people willing to help answer even the goofiest of questions. I’ve asked a fair number of those goofy questions, and the help I received encouraged me both to stick with Ruby and to try to return the favor. Please support that.

A Random Set of Guidelines

Assorted do’s and don’ts. If you can think of more, please add them in the comments.

Don’t top-post

See here.

Before retorting with how this or that mail reader or client makes top-posting the default, consider this: the idea is to make things easy for the readers, not for you, the poster.

If the goal is have people read, and understand, what you are posting, then place you reply in context, and trim away irrelevant text.

If you are unpersuaded by arguments against top-posting (and many are), know that many people will simply not bother with what you post.

Do your homework

Ruby is a great language, fairly intuitive to many people, but sometimes you get stuck trying to figure something out. It may seem easy to dash off a note to ruby-talk asking, “How do I do foo?”, but first apply some due diligence. Use Google. Use ruby-doc.org (Handy tip: Ruby-doc.org uses a custom Google search focused on Ruby sites. There’s a special search URL as well: http://www.ruby-doc.org/q/your+search+terms+here.)

Search the ruby-talk archives:

http://groups.google.com/group/ruby-talk-google
http://www.nabble.com/ruby-talk-f13890.html
http://blade.nagaokaut.ac.jp/ruby/ruby-talk/index.shtml.

When you do post, explain what steps you’ve taken to solve the matter on your own. This serves two purposes. First, it shows people you are diligent, making more people more likely to want to help you. It also avoids wasting time with people suggesting things you’ve already done or know about.

Whenever possible, show your code. If you have more than a dozen lines or so, use a pastie site, such as Gist.

Be specific

If you have a problem, give details about your environment. What operating system? What version of Ruby?

Know, too, that there are specialized mailing lists for many Ruby tools and applications. For example, if you have a problem with Rails or Ramaze, please ask on the Rails or Ramaze mailing lists. You are more likely to get a faster, more accurate response on the proper list.

Ask concrete questions. Explain what you are trying to do, what results you get, and how those results differ from what you want or expected.

Don’t threadjack.

That is, do not reply to a post with starting a new topic. If a thread starts to drift off-topic, please consider starting a new thread with a more appropriate topic.

Repetition is not an argument

Don’t expect anyone to change their opinion because you’ve repeated your same points over and over. Accept that sometimes people will never, ever, agree with you. I know, it’s weird, but true.

Watch for perma-threads

There are some topics that come up at regular intervals. Adding static typing to Ruby. Best GUI toolkit. Best IDE. Adding significant indentation.

Before posting, see if you are not simply repeating what has been said. Check the archives. If you really feel you have something new to add, post, but please show that you are familiar with prior discussion.

Conversely, if you see a post that looks to be a perma-thread, don’t assume it has been discussed to death (although that is possible). Certain topics, such as GUI tools or IDEs, see new additions and advancements over time. It doesn’t help to direct people to a thread from last year as the final word on evolving technology.

Walk the walk

People often ask for one or another change to the Ruby language or standard library. This is good, this is how languages evolve.

Well-considered change requests should be posted to the ruby-core mailing list.

Before proposing any change, see if someone hasn’t already implemented it as a library. There are a few libraries, such as Facets, that provide many extensions.

If there is no existing code, see if you can first implement it yourself.

For example, you may think it be would super cool awesome if the Array class could tell you what elements were of a certain size:

  a = %w{ foo bar bar thisoneisdiffernt }
  short_words = a.length_is 3

Before arguing in the abstract just how magical this would make life, code it yourself:

  class Array
    def length_is length
      self.select{ |i| i.size == length }
    end
  end

Make it a gem, or a gist pastie, or otherwise available for others to try. Then explain why it needs to be added to the language rather than used as a gem.

If, for whatever reason, you cannot implement it (even a weak version), explain why.

The bottom line is this: Many, many suggestions have been made, many with the presumption that someone else is expected to do the heavy lifting, swayed only by rhetoric. That’s unfair, and unproductive..

When first attempting to code it yourself, certain results are likely:

You discover that there is no need to build it into the language, since it is trivial to add (e.g. using a gem)
You discover that it is not so easy to add as-needed, but you now have the code for it, so adding it to the language would be that much easier
You discover that, now that you have a working version, you don’t use it as you expected anyway
You find out that some things are hard to do

Best of all, the effort should make you a better Ruby programmer.

Solve the problem, not just a problem

james.britt@gmail.com (James Britt) — Mon, 13 Apr 2009 20:11:00 -0000

So you decide you want a way for a number of people to post short articles to a Web site, and maybe allow for other people to leave comments. What do you do? That’s easy: jump to the white board and start sketching out a vast array of boxes, blobs, and arrows that define a sophisticated content management system with multi-level admin roles, content versioning, threaded discussion boards, syntax highlighting, the works.

Right?

Don’t be too quick to judge. It’s easy to fall into the trap of defining the wrong requirements for a project.

Part of the reason is that building software is (or should be) fun, and often bigger projects are more fun. There is also the tendency to think about “what if”, imagining all the things that maybe one day who knows you never can tell might be needed.

People also tend to think in terms of what’s familiar, of how things have been done in the past or by others.

There are many ways to satisfy the needs described in the first paragraph. Some don’t require writing any software at all.

For the Ruby Best Practices blog, the general goals were modest. Allow a core set of people to easily add new content. Allow other people to contribute content as well, but only with the OK from someone in that core group. (BTW, there are eight of us in the RBP blog team. See here for my take on the RBP team logo)

We wanted to allow the use of Textile, and not make people use a browser for editing. Basically, turn simple flat files into a Web site with minimal fuss.

Korma takes an interesting approach to building Web sites. The whole app is ~230 lines of Ruby. Its key function is to take content from a Git repository, run it through some templating, and write out the site files.

Relying on Git for that back end is stunningly perfect. Git provides versioning, access control, and distributed contributions.

It becomes the database layer common to most blogging tools. For free. Right off the bat, no need to write any admin tools or content versioning code .

At the heart of Korma is the grit gem. As the project blurb says, “Grit gives you object oriented read/write access to Git repositories via Ruby.” Very sweet.

The korma.rb file takes two arguments. The first is required, and is the path to a git repository. The second argument is optional; it tells Korma what directory to use for the generated content, and defaults to ‘www’, relative to where you invoke the program.

The app uses grit to reach into the current contents of the repo and parse the needed files. Files have to be committed to be accessible to Korma.

There is a configuration file that describes some basic site metadata, such as the base URL, the site title, and the author list. When called, korma.rb grabs this config file, sets some Korma::Blog properties, and then writes out the static files.

An early version of Korma used Sinatra; basically, Korma was a lightweight Web app to serve the blog posts. But as simple as it was, it was overkill, since there was no real dynamic content. It made no sense to have the Web app regenerate the HTML on each request, since it changed so infrequently.

A next version replaced the Web app part with static files, making it a straightforward command-line program. This solved another problem: how to automate the regeneration of files. The answer: use Git’s post-commit hook to invoke the program.

For example:

   #!/bin/sh
   # File .git/hooks/post-commit   
   /usr/local/bin/ruby /home/james/data/vendor/korma/korma.rb /home/james/data/vendor/rbp-blog /home/james/data/vendor/korma/www

Early versions also used Haml for site-wide templates. Not being a fan of Haml, I added in a configurable option to use Erb. It was nice and all, but it was a feature without a requirement. No one was asking for configurable templating, so that option was dropped and Erb replaced Haml as the default.

If you are wondering why working code was removed, consider that any code you have is something you have to maintain. As bug-free and robust as you may like to think it, no code is easier to maintain than no code. Configurable templating was simply not a problem we were needed to solve, and a smaller, simpler code base is more valuable than a maybe “nice to have.”

There was some discussion about the need or value of allowing comments. In the end they were deemed good, but there was no good argument for hosting them as part of the blog site itself. That meant a 3rd-party solution (in this case, Disqus) was perfectly acceptable. Again, a goal was to have comments, not to write a commenting system (as entertaining as that may be).

Using Git allows for yet another feature for free: easy one-off contributions. In many systems, allowing anyone to contribute means creating an account, granting some sort of access, managing all the new user annoyances. Or, an existing user has to play proxy, accepting content and entering it into the system on behalf of the real author. That’s work! With git, one can clone the repo, add new content, and issue a pull request back to the master branch. Anyone with commit rights to the master can then merge it in (or politely decline). No-code features FTW.

None of the blog design requirements are written in stone, and they may change tomorrow, but by identifying the real needs, addressing what was deemed essential, offloading what we could, and skipping the feature bling, we have a system that is easy to understand, easy to maintain, and easy to change.