On Writing Well: Exposition or Code

Posted by Jeremy Voorhis Tue, 29 Aug 2006 02:12:00 GMT

When I signed on with O’Reilly Media to write Rails In a Nutshell, I was sent a welcome package that included an audio recording of On Writing Well. One idea that On Writing Well stresses is that you can improve anything you write by cutting 50% of it. The recording even includes a stopping point where the listener is to stop and shorten the last thing he or she has written by 50%.

PuneRuby has posted an interview with Jean-Christian Fischer that I will quote:

I have the 50% rule as a measure of success: I’m usually able to reduce code I have written by 50% by applying better ruby techniques. I try to do that on my code and rejoice when I’m able to achieve that reduction.

I agree. Although some programmers might think this means obfuscation, Ruby offers many ways to cut your code and make it more acceptable. Some places to start:

  • Only use return when you really need multiple return paths.
  • Can you rewrite a conditional statement with a modifier?
  • Are you trapping an exception within a begin block? Do you really need that extra scope? Example: replace
    
  def catch_a_fish
    begin
      @line.cast
    rescue InsufficientBaitError
      @line.replenish_bait
    end
  end
    with 
    
  def catch_a_fish
    @line.cast
  rescue InsufficientBaitError
    @line.replenish_bait
  end
  • Are you handling an exception? Can you use the rescue modifier? Example: replace 
    
  def deep_copy
    @widgets.map do |w|
      begin
        w.dup
      rescue
        w
      end
    end
  end
    with 
    
  def deep_copy
    @widgets.map { |w| w.dup rescue w }
  end
  • Can you rewrite a simple call to Enumerable#map with Symbol#to_proc? Rewrite
    
  @objects.map { |o| o.attribute }
    as 
    
  @objects.map &:attribute

Ruby has many syntactical elements that help you write denser, more readable code. Experiment and see what matches your taste, and more importantly, contributes to readability.

10 comments

Is Your Test Suite Acceptable?

Posted by Jeremy Voorhis Fri, 25 Aug 2006 23:43:00 GMT

Is your test suite acceptable? I mean acceptable in the Chomsky sense of the word. Here are a few heuristics:

  1. Do you understand your test at first glance?
  2. Do you understand the code that is being exercised after reading your test?
  3. Do your tests tend to have 1 assertion or 10 assertions? More?
  4. Do your tests have cryptic names, like test_component?
  5. Are you using external test fixtures? If so, how much time do you spend reading and cross-referencing them?
  6. If you are using external test fixtures, how well do they serve your needs? Are you creating tests that require you to cross reference external fixtures and temporary objects?

Here are some design principles that are useful for lowering the mental overhead your test suite requires:

Give your tests meaningful names

If you can accurately infer what your test is trying to accomplish by reading its method name, you can understand it much faster. It’s even more helpful when that name appears in a report generated by a test runner!

Favor acceptability over DRYness

Which is worse: repeating a string literal two or three times within a test, or losing time reading the test later? Of course, this is a tradeoff, and both sides have cumulative effects.

Group your tests according to their context

Just because all of your tests exercise the same class, they don’t all have to live together. If you are testing a Stack class, don’t be afraid to separate your tests for an empty stack and your tests for a full stack. You can then use the setup method to instantiate the kind of stack you are testing, and your tests will be easier to understand. Conversely, when tests that are grouped together rely on different contexts, you will spend longer establishing your mental model when you read these tests later.

Write individual tests for a method’s individual behaviors

Rather than writing one test for one method, try analyzing the expectations you are placing on your method. Let’s use a method that accepts a blob, generates a filename and saves the blob to the named file as an example. Write one test to ensure the file name is generated correctly, and write another test to ensure the contents on disk are correct.

Keep your tests short

If you can use setup or some other means to create all the context you need, and your tests target individual behaviors, you can write a suite of tests that is very scannable by human eyes.

Avoid external fixtures when feasible

Relying on external fixtures may cause you to spend much time cross-referencing your test against many fixture files. What’s worse, changing an external fixture for one test may have the side effect of breaking other tests!

Posted in Testing | 5 comments

Craft Workshop Rescheduled

Posted by Jeremy Voorhis Thu, 24 Aug 2006 22:23:00 GMT

Due to some scheduling difficulties, the Craft: Understanding the Web Through Ruby on Rails workshop has been rescheduled. The new dates for the workshop are 9-10 November.

The workshop will be held at the same venue, and the cost will remain the same. Early registration has been extended until 16 October, so attendees who register before 16 October may still pay the early-bird special of $350. On 16 October, the registration fee will be raised to $450.

For more information about the workshop, check out the workshop’s homepage as well as my announcement .

no comments

PuneRuby Interviews Ruby Developers

Posted by Jeremy Voorhis Wed, 23 Aug 2006 17:55:00 GMT

Satish Talim, founder of Indian Ruby developers’ community Pune Ruby, has interviewed several Ruby developers via email and posted the responses to the group’s blog at http://www.puneruby.com/. Interviews that I found especially interesting featured Bruce Tate, Chang Sau Sheong, Phil Thompson and Topher Cyll. My interview was just posted today as well.

Two curious facts about the interview series:

  1. Only two of the nine interviewees was from a country other than the United States. One was from Singapore. None were from India; surely PuneRuby has a few Ruby rockstars of its own.
  2. Over half of the interviewees are from Portland, Oregon. The other four are friends and acquaintances of mine through our own Portland Ruby Brigade.

Posted in Ruby | 5 comments

My Killer App For CRM

Posted by Jeremy Voorhis Tue, 22 Aug 2006 23:59:00 GMT

While I was working at PLANET ARGON, I took notes about client interactions and steps I had taken to resolve problems in the company’s intranet. Keeping our notes online was a reasonable thing to do when other team members need to access them. I understand some companies pay quite a lot for customer relationship management software.

Now that I am independent, I need to have my own way of capturing these kinds of notes. One of the benefits of working alone, however, is that I am free to take satisfaction in cruder forms of technology. While roaming about Powell’s City of Books, one of the members of the latest family of Moleskine products grabbed my attention: the Moleskine address book. Most address books have specific fields for cell#, fax#, etc., thus rendering them completely useless for my purposes. The folks at Moleskine were wise enough to include nothing but plain, lined paper and a full 10 pages for each letter in a medium-sized format. Now I can keep contact information and notes together in one place.

Other possible uses: travel directions, pasting in business cards, autograph book at conferences…

4 comments

Is your test suite valuable?

Posted by Jeremy Voorhis Mon, 21 Aug 2006 21:39:00 GMT

Is your test suite valuable? I mean, is it actually making your code better? Answer the following questions to find out.

  1. Are your tests inexpensive to run?
  2. Are there any inhibitions to running your full suite of unit tests before every check-in?
  3. Is the process of running tests uncomplicated?
  4. Do all of your tests pass?
  5. In practice, are your tests your first line of defense against new bugs? Ideally, you can know if you have introduced a bug within minutes.
  6. Is test-first development actually preferred by your team? Writing tests should be rewarding.

Posted in Testing | 5 comments

A New Direction

Posted by Jeremy Voorhis Thu, 10 Aug 2006 17:20:00 GMT

I have resigned from the position of Lead Architect at PLANET ARGON. While the experiences I have had there have been invaluable to me, it is time for me to explore a few specific areas of my career on my own. I am leaving behind a highly competent team and I look forward to seeing what they will accomplish as time unfolds.

In case you are wondering what’s next, I am dedicating greater portion of my time to my forthcoming book, Rails In a Nutshell, which will be published in 2007 by O’Reilly Media. I am also eager to spend even more time developing my Craft series of workshops, which begins on September 1-2. Finally, I will be available for contracting for Ruby development projects, acting as an developer, but also as a trainer and a mentor.

The common theme in all of these endeavors, giving direction to my future, is that I want to ultimately develop as a communicator; I want to connect with clients as well as fellow developers with the intent of improving our craft and sharing what we learn. Towards that end, I also intend to increase my community involvement, beginning at the Portland Ruby Brigade. See you there!

email address: jeremy at jvoorhis dot com

Posted in Rails, web development, Ruby, PLANET ARGON | 9 comments

Announcing: Understanding Web Architecture Through Ruby on Rails

Posted by Jeremy Voorhis Mon, 07 Aug 2006 20:26:00 GMT

I am pleased to annnounce that I will be hosting a Ruby on Rails workshop titled Understanding Web Architecture Through Ruby on Rails here in Portland, Oregon on 1-2 September. Early registration is only $350, and will be raised to $450 on 18 August.

This workshop will be the pilot of my Craft series of workshops, aimed at raising the level of our craft not only as Ruby on Rails developers, but as contributors to the web as a whole.

Summary

Session 1

  • Introduction to Web Architecture: Resources, Representations and HTTP
  • Modeling Resources: Identity, Hierarchy and Meaning

Session 2

  • Architecture of Ruby on Rails
  • Domain Modeling With ActiveRecord
  • Creating Resources With ActionController
  • Creating Representations with ActionView

Session 3

  • Building a Time Tracker Application

Session 4

  • Extending the Time Tracker

Full details may be found at craft.jvoorhis.com.

UPDATE

Today is Friday, August 18. Today is the last day to sign up for early registration – $100 below the full registration price. If you had planned on attending but haven’t registered yet, now is the right time.

1 comment

Older posts: 1 2 3 4 5 6 ... 18