positive:

• distractions are less common, it needs to be something that distracts both of you; get back into “the flow” faster (also a reason to do TDD); helps those among us with Attention Deficit be productive at *all* (this is an important one for me).
• higher bus number, more team ownership of code, less personal jurisdiction
• communication of design decisions is much easier/faster: “here, let me show you what I mean.”
• creative tension, generally leads to better design decisions, better names for variables/classes/etc, better quality. Automatic “code review” on all pair produced code, at the time when it’s easiest to enact suggestions.
• because you’ve cut the number of concurrent tasks your team can work on in half, you’ve made it easier to coordinate a larger team and juggle the team’s current tasks and priorities. In other words, pairing makes it easier to scale the team. Your team members are less likely to step on each other’s feet.
• team culture grows more quickly, quick tips (did you know how to do X in vim? see how inject makes this simpler?) spread through the team more quickly. This could be mentoring of junior developers, or new fresh ideas for senior developers, or peers balancing and pulling each other out. A pairing team tends to gravitate towards the *highest* common denominator, versus individuals working together, tend to be bottlenecked by the weakest link.
• pairing and TDD(BDD) go great together, even if you aren’t occasionally ping-pong pairing
• morale boost: team camaraderie grows faster.

difficult or negative:

• requires soft-skills, i.e. getting along with other devs, communicating, not being stubborn, etc.
  • good pair programming is a learned skill, but often is treated like something that should Just Work (and is obviously no good if it goes poorly on the first try).
  • the pairing experience can be spoiled by either person in the pair.
  • programmers are overwhelmingly introverts, and we would much rather just work (and be) alone, even if it isn’t the best thing for the team.
• fewer tasks can be done concurrently. When you are being asked to finish 20 “highest priority” tasks by yesterday, even though it is probably faster to have four people pair on them, doing only two tasks at a time, our instincts are to divide and conquer (four tasks concurrently).
• either there is no music (no headphones) or you need to agree/compromise on what to listen to.
• it can be hard to replace the personal pride of “I did this” with the team pride of “we did this”, even if “We did this” really means “I did this and so-and-so helped out and it was better than if I did it alone.”
• pairing (done right) can be more exhausting than working alone. this is mostly because you aren’t getting distracted as much, you are forced to defend your (often bad) ideas, and you have gotten more done. but still, it’s more *work* than working alone.
• working with different editors is tricky. doable, but tricky. it slows you down and dampens some of the benefits.
• remote pairing is tricky. doable, but tricky. it slows you down and dampens some of the benefits.
• Awkward pairing:
  • mindless routine tasks feel like a waste of time, and sometimes they are.
  • research and spiking and experimentation are sometimes very appropriate for pairing, sometimes not at all, and it’s hard to tell when is which (very context sensitive).
  • pairing without the cadence of TDD(BDD) often feels awkward. (ahem… perhaps you should start to TATFT then!)
  • pairing done wrong (and sometimes even “done right”), might not *feel* very productive to one member of the pair. at that point, that person probably feels it is a waste of time, and the other person feels slightly guilty for wanting to pair. Note, this might be far more about emotions and perception than about logic and empirical reality.

In summary

Because of the above positives, pairing usually results in better code, done in less time, with more team members able to take ownership over it, than if the developers had worked on it individually.  Programming isn’t constrained by typing speed but by thinking, and two heads are better than one.

The above negatives mean that (in my experience), even when an entire team agrees that pairing is a good thing (in the abstract or based on experience) and the team has agreed to pair some or most of the time, the team often pairs less often or gets less out of it than expected.

Unfortunately, although I’ve experienced all of the positive reasons for pairing, I tend to get far too influenced and disheartened by the negative.  As a result, I usually pair far less often than I know I should, and both I and my team are less effective as a result.  Any suggestions?

See also these posts: Obie Fernandez, responding to criticism of his pair programming comments, Mike Hill: How TDD and Pairing Increase Production.

Each individual example (”it” blocks) should be able to run by itself or in any order and the example group (”describe” blocks) may run in any order, even in random order.

Corollaries:  If you change any global or shared state inside an example, please ensure that you reset it to a baseline before the next example.  If you depend on any global shared state, please set it to a baseline before this example.  Both of these are achieved easily with a before(:each) block (or after(:each) in some cases).

Nine times out of ten, when I see a weird sporadic build failure and there is a before(:all) nearby, I can fix it merely by changing it to a before(:each).  The original author of the spec assumed that it would always run front to back and then proceed to change global or shared state in some of examples (sometimes inadvertantly).

Although I’ve phrased this advice for rspec, it applies equally to test/unit in ruby, or xUnit on any platform.

Here are some guidelines that help me follow another important principle: test the interface, not the implementation.

• If the test looks like a copy and paste or trivial transformation of the production code, something is probably wrong.
• “Complex” code should be avoided in specs, especially if it is a reproduction of the production code (e.g. SQL, ActiveRecord::Base#find conditions, and non-trivial regular expressions).
• I prefer business language examples over technical language modeling (e.g. “belongs_to” or “verifies_format_of“).

Some (bad) examples

As an example of what I’m talking about: Testing Named Scope with shoulda’s should_have_named_scope (also should_belong_to, should_have_one, and should_have_many from shoulda’s ActiveRecord Macros).  The rails documentation for named_scope also suggests that you can test it by looking at the proxy_options method.

What’s wrong with the following?

# from rails rdoc:
expected_options = { :conditions => { :colored => 'red' } }
assert_equal expected_options, Shirt.colored('red').proxy_options
# from shoulda
should_have_named_scope :eighteen,  :conditions => { :age => 18 }
# example of the sort of thing I've seen in codebases I work with
Model.should_receive(:find)
     .with(:all,
           :conditions => ["foo => ? and (bar like ? or blatz in ?)",
                           foo, bar, blatz]).and_return([...])
# I've also seen bastardizations of the above for SQL building
# code which gets piped into a mocked Model.find_by_sql

Should your specs care if those conditions are created as hashes or arrays, or even at all?  From the outside, it is completely unimportant whether it uses named_scope or a conditions hash behind the scenes.   What you should care about is whether or not they return the correct objects, don’t return the wrong objects, and (maybe) stack appropriately with other named scopes or finder methods.

More practically, those conditions hashes qualify as production code that represents the very core of the business logic you are supposed to be testing.  If you expect that {:colored => 'red'}, but the column name is “color” or the value is actually stored in hex RGB, you won’t have a hint that the code is broken.  If you expect that {:age => 18}, your specs won’t remind you that you were actually supposed to be matching 18 and older.  If you expect the wrong SQL, then your specs have lost their power to help you find the right SQL.  You are wide open for letting sloppy bugs through the very specs that should have caught them.

So, these mocks verify expectations that don’t matter much, but they copy and paste the bits that do matter, the parts you really should be testing.   You are gaining “code coverage”, and thus false confidence.  It’s like a weird form of regulatory capture.  However, a few examples of what you should and should not match would clarify many mistakes immediately.  When working with examples, the boundaries that you need to poke often become obvious.

Good examples: Named scope or finder methods

# the following lines would generally be done using factories
good_examples = [FooBar.create!(...),
                 FooBar.create!(...), ...]
bad_examples  = [FooBar.create!(...)
                 FooBar.create!(...), ...]
# now exercise the code under test
results = FooBar.my_spectacular_finder_or_named_scope(...)
# expectations
good_examples.each {|e| results.should     include(e) }
bad_examples. each {|e| results.should_not include(e) }
# or perhaps
results.should == good_examples

This wins in almost every regard over mocking SQL or checking the conditions hash or proxy_options.  It is clear what is being tested and how. We are oriented towards results, not implementation. The examples should make it clear if we are missing anything.

However, it is not as concise, but it doesn’t matter how concise bad specs are.  We could make macros to make the above code more concise, while still retaining the clarity.  It would also be nice to follow the “one assertion per example” rule, so that developers get fine grained failure notifications.

And it may be slower if it hits the DB, but it doesn’t matter how fast bad specs run.  This is a trade-off  of the ActiveRecord ORM style: to test that you wrote the right queries, you need run the queries and verify the results.

Alternatively, this style is well suited to cucumber or fit tables, enabling the subject matter experts to easily contribute their own examples (and detect mistakes that the developer wouldn’t know about).

Good examples: Validations

Sorry to pick on shoulda above… but it was the easiest example to google for.  To balance the scales there, I do like two of the macros shoulda uses for validations: should_allow_values_for and should_not_allow_values_for.  I also wrote up a short little rspec matcher that does about the same thing.

# shoulda's macros
should_not_allow_values_for :phone_number, "abcd", "1234"
should_allow_values_for     :phone_number, "(123) 456-7890"
# my rspec validation matchers
it { should.reject(:phone_number).of "abcd" }
it { should.reject(:phone_number).of "1234" }
it { should.accept(:phone_number).of "(123) 456-7890" }
it { should.accept(:phone_number).of "(123)456-7890" }
it { should.accept(:phone_number).of "123-456-7890" }

Specs that verify that the “appropriate” regular expression was sent to validates_format_of scare me.  Regular expressions aren’t just opaque blobs, they are a DSL, a programming language in their own right.  Regexes are code, and we test code.  You shouldn’t care that a particular regular expression is sent to a particular rails validation macro; you care that your model validations work appropriately, i.e. accept some values and reject others.

When I’ll ignore my own advice

Here are some contraindications:

I just don’t know what to do:  I might be exploring new realms, and feel a bit lost.  Writing some specs, any specs, is a good way to learn, a good way to keep focused while working, and a good way to just get the job done (TATFT).  Even if the specs are no good and tightly coupled to implementation, at least they can act as “change notifiers”.  The next time someone edits the code, they’ll trigger a build failure that will force them to re-evaluate the specs.  Maybe they’ll come at it with more knowledge and improve the situation.

Pair programming significantly reduces the likelihood of this occurring.

too much yak shaving, time to punt:  I know what to do, but it’s too much work.  For example, if you have some models that are so truly heinous that you cannot simply or clearly create them right there in your spec, my first instinct would be to invest some time in my factories.  It’ll pay off.  But that is yak-shaving, and it may be too much for now.  “Emergency mocking” is excusable.  Document your compromise in the spec, and hopefully that technical debt will be repaid in the future.

But excessive mocking can feel like yak-shaving too.  Weigh your options before going the “quick and dirty” route; it might actually be slow and dirty.

debugging and sanity checks:  If I’m trying to figure out why the results aren’t what I expect them to be, I’ll probably throw in some extra assertions about the implementation, as a sanity check.  I might delete them when I’m done or keep them in but document them as special.

There may be other contraindications, but these are what come to my mind.

What do you think?

“I’ve been using Ubuntu for quite some time now and, honestly, I’m getting a little tired of having everything handed to me. I want to switch to a less noob friendly distro.”

“Is anyone else worried, that because Ubuntu is so stable, and because you rarely have to fix issues, that your Linux knowledge is fading?”

“I want to use a distro that will challenge me to learn how things work.”

And so on…

My response

You might enjoy giving Debian a try.  You also have the option to go with Arch Linux or Slackware or Gentoo or Linux from Scratch, etc.  You could also install Ubuntu JeOS or Ubuntu Server (or another distro’s simpler versions) and then only apt-get or compile software as you want it.

If you are the type of person making the same sort of remarks as above, you obviously have a lot of time.  I’m jealous of you.    But lots of time is not limitless time.  So if you want a challenge that will pay off, I suggest that your time might be better invested by sticking with Ubuntu (or Debian), and simply diving under the hood a bit more.

I don’t mean to say that any of the other distros or paths you might choose aren’t valid… one of them may well be a better fit for you and your ambitions than Ubuntu.  But, unlike proprietary OSes, Ubuntu’s hood is not welded shut.  Much of the “magical” hand-holding is done in shell, perl, or python scripts.  So you may not even need to look further than your own box for the source.   And just because Ubuntu is intended to be user-friendly with no-assembly-required doesn’t make it any less configurable or less geek friendly, nor does it get in the way of your deconstructing and reconstructing it (and wondering about those leftover pieces at the end).  The wires and pipes are all showing, there’s no magic going on, and you are in control of your box.

for example

Are you interested in mucking around with webservers?  Then go ahead and compile apache/nginx/lighttpd/etc from source yourself.  Muck about with the config files.   Spend days with man pages and google and upstream’s bugtrackers. Use the distro’s packages as a “cheat sheet” to see what patches, config, scripts, etc the distro maintainers used, and then selectively pick and choose your own way from there.  Rig up benchmarks or compare them on features, ease of configuration, etc.

Post your troubles/successes/thoughts/etc to mailing lists and blog about what you’ve done.  Post the results to launchpad or github or some other publicly accessible DVCS repo.  Respond to the comments of the people who tell you you’re doing it all wrong (many of them are right).  Adjust your approach and iterate until something else more interesting catches your interest.

other examples

Or do the same thing with…

• mail servers (postfix/sendmail/exim/etc)
• filesystems:
  • local: ext3, XFS, ext4, etc
  • LVM, software RAID
  • networked: NFS, Samba, AFS, etc.
• X Windows
• GNOME or KDE
• Dig into HAL and D-BUS and all of those magical goings-on beneath the covers, and learn how to make them do your bidding.
• Learn about LSB and freedesktop.org.
• Figure out what Ubuntu did wrong with pulseaudio, and then fix it or swap it out with another audio stack.
• Learn how dpkg/apt does its magic,
  • understand the Debian packaging guidelines (and why they are wonderful or horrible or just don’t meet your needs or desires),
  • and start your own Launchpad PPA for software packaged the way you like it.
• Run “ps faux” and make it your mission to discover the purpose behind every running process and how it got there… and then remove or replace the ones you don’t want.
  • Run “dpkg -l” and do the same thing with every package on your system.
• Install bootchart and figure out how to shave several more seconds off of your boot-time.
• Restore the geeky log messages to the Ubuntu boot screen.
• Spend a week figuring out out to use wmii,
  • another week with xmonad,
  • and another with awesome;
  • Ubuntu doesn’t force you to use metacity or compiz (or GNOME).
• Install the 64-bit version,
  • discover all the myriad places it breaks horribly,
  • and file bug reports with all of those packages.
• Obsessively install the latest beta version of some software you like a lot,
  • and report the new bugs on every release.

When you’ve picked out an interesting challenge and jumped into it: Post, respond, adjust, iterate.

personally

I personally use my own compiled version of ruby and related libraries, because the ruby upstream maintainers released a new “minor” version with myriad backwards incompatibilities (and a few segfaults), and the Debian/Ubuntu maintainers followed their advice and upgraded. But the software at my day job still needs that older version. Ubuntu doesn’t make it hard to do this for the packages that I know and care about, and I get to continue relying on Ubuntu for everything else I don’t care about and don’t want to spend time on (right now).

Several years ago, I compiled compiz/beryl myself. Then I switched to someone else’s apt repository. Now I just use the compiz provided by Ubuntu (and I can spend those regained several hours a week geeking out on something else).

Years ago, I used debian unstable for everything.  Now I really appreciate the stability and twice a year upgrades of Ubuntu.  Generally, my “ls /etc/apt/sources.list.d/ | wc -w” stays between 2 and 6 (currently 3).  Occasionally this less stable software is an unwelcome source of bugs and a time-sink.  But I try to always file bugs.

So then…

The opportunities for non-hand-holding non-newbie stuff in Ubuntu is limitless. You could transform yourself into one of the gurus that holds other people’s hands. You could even make it your goal to become a Debian package maintainer or an Ubuntu MOTU or a GNOME contributor or a KDE contributor or a $FOO contributor (which will look mighty nice on a résumé).

but practice safe geeking

But above all, consider doing your experimentation on a spare computer or in a VirtualBox VM, so that when your friends ask you to play a movie or browse the web or do something simple (that their “welded-shut” Mac or Windows box can handle just fine), you don’t need to say “oh my computer’s currently hosed… {sound,X Windows,TV Tuner,booting,etc} doesn’t work. It’ll be back up in a week.” In my experience, that excuse can get kinda embarrassing.

From xkcd.com, Cautionary, CC licenced By-NC.

>> defined? RAILS_ENV
=> "constant"
>> defined? RAILS_ENV && RAILS_ENV == "development"
=> "expression"
>> (defined? RAILS_ENV) && (RAILS_ENV == "development")
=> false

D’oh! (let’s ignore for now the issue of whether or not the “fixed” code is reasonable to run anyway)

I was curious to see if the expression was evaluated, and it appears that it is… sort of:

>> def foo
>>   $stderr.puts ":foo"
>> end
=> nil
>> def bar
>>   $stderr.puts ":bar"
>>   raise "hell"
>> end
=> nil
>> defined? foo
=> "method"
>> defined? bar
=> "method"
>> defined? foo || 1
:foo
=> "expression"
:bar
>> defined? bar || 1
=> nil

Notice: the methods were executed, but the exception from bar was caught and squirreled away somewhere, and defined? the returned nil, even though the method and expression were certainly “defined”.

I’ve always been a little bit bemused by the default ruby test/unit and rspec output: a series of dots, one for each passing test (or example), and the dots become “F” characters in the event of a failure.  Most importantly: it’s simple, unambiguous about pass/fail, and easy to read at a glance, so no problem there.  You get a feel for the speed at which the tests are running, and you can visualize how many tests have run already.  And it’s easy enough to have them output in color (red or green), to make the errors visually pop out.  And it’s drop dead simple.  That’s good.

So what’s missing?

(for my tastes)

• Immediate Feedback: Yeah, the default output gives me an “F”, but what am I supposed to do with an “F”? I won’t know where and what that “F” was until the end of the entire test run, when the summary is dumped.  When running through a (functional) test suite that takes three minutes or even fifteen minutes, that just doesn’t work.
• Concise output: if everything is passing, I don’t need to see 4000+ dots displayed across my screen. It would be nice if the entire output would fit into a single line (when there are no failures).
• Percentage: A nice to have, not a need to have. But knowing how many tests have already run is generally not as interesting to me as how many tests are there total, and what percentage of them have run.
• ETA: This isn’t so important for the short test runs that I do over and over again during the BDD cycle… because I expect those tests to finish in under 10 seconds anyway.  But anything more than 10 seconds, and I get distracted. An ETA helps me limit my distraction.

So what do I do about it?

Basically, what I want is a progress bar and that the errors and warnings be displayed immediately. I also want warnings to be printed for slow specs. When using color, I want the entire progress bar printed in green if everything is good, yellow if there has been a warning, and red if there has been an error.

Fortunately, rspec makes it very simple to write a custom output formatter. So, a couple of weekends ago, I threw something together in about half an hour. I’ve used it ever since, and I’m pretty happy with it (I’ve tweaked it a little bit).

What does it look like?

A static image doesn’t really show off the progress bar very well, but here’s a screenshot (click thumbnail for full-size):

And here is a video, so you can see it in action (very low quality, sorry):

The code

http://ekenosen.net/bzr/rspec_support/compact_progress_bar_formatter.rb

It’s currently hosted in a bzr branch, but I’ll stick it up on github if anyone really cares about that.  Also, it depends upon the progressbar gem, so you’ll need to install that.

To use it

The location you download the script to is not important, but this is where I’m (currently) keeping it. You could also use bzr to pull down the entire branch.

$ gem install progressbar
 
$ mkdir -p ~/lib/rspec/
$ cd ~/lib/rspec
$ wget http://ekenosen.net/bzr/rspec_support/compact_progress_bar_formatter.rb
 
$ spec --require ~/lib/rspec/compact_progress_bar_formatter.rb -c -f Spec::Runner::Formatter::CompactProgressBarFormatter path/to/specs

I’m currently using some bash aliases to keep the spec command line nice and short. Perhaps there’s a better way?  In ~/.bash_aliases:

alias  spb='spec        --require ~/lib/rspec/compact_progress_bar_formatter.rb --format Spec::Runner::Formatter::CompactProgressBarFormatter --color'
alias sspb='script/spec --require ~/lib/rspec/compact_progress_bar_formatter.rb --format Spec::Runner::Formatter::CompactProgressBarFormatter --color'

For rake tasks, I use a spec/local_spec.opts (spec/spec.opts is checked into version control as a default).

Nitpicking

I cheated: I didn’t develop it BDD-style.  I intend to fix that soon by rewriting it spec-first; certainly before adding any more functionality. TATFT indeed.

I’d really like to be able to send the threshold (for reporting of slow specs) in on the command line.  It might be easy to do, I haven’t looked into it… I’m currently just editing the file every time I want to change the threshold (e.g. normal specs run with a threshold of 0.1 sec, functional specs run with a threshold of 5 or 10 seconds).  Messy.

Also, it would be nice if the command line didn’t need to be so long… perhaps a supported gem/plugin system for rspec?  If that were easily doable, then I would probably package this up into a gem.

I had to break into the progressbar’s internals a little bit… it didn’t publically expose all of the functionality I wanted.  Still, that’s better than creating my own progressbar library.

Any non-determinism in tests is dangerous, and Time.now and its close cousins are certainly on that list.  Whether the code which depends on the current date is in the production code or in the spec code, we’ll need to be very careful of it, lest it trip us up.

I’ve known this for a long time… but I just spent about 45 minutes perplexed with a particularly stupid bug that simply required an attentive eye to unravel… I’ll gladly share my debugging session (condensed for time and minus the aggravation and going in circles), and hopefully save someone else the hassle:

>> DateTime.yesterday < DateTime.now
=> true
>> DateTime.tomorrow < DateTime.now
=> true

Well that shouldn’t ever happen.  Confused yet?  Or do you already know where this is going?  I spent a great deal of time wondering if it was some weird interaction between the Date, Time, and DateTime classes (and trust me, those weird interactions do exist, although maybe they weren’t the cause of this particular bug).

>> DateTime.tomorrow
=> Sun, 24 Aug 2008
>> DateTime.yesterday
=> Fri, 22 Aug 2008
>> DateTime.now
=> Sat, 23 Aug 2008 23:24:35 -0400

Ummm… nothing that would explain the comparison results above… but that’s curious… DateTime.now gives a different inspect output than the others.  I wonder why?

>> DateTime.yesterday.class
=> Date
>> DateTime.tomorrow.class
=> Date
>> DateTime.now.class
=> DateTime

Intriguing.  Certainly not what I expected, given that all of these values were obtained from class methods on DateTime.  Perhaps this means that the comparison requires some coercion to work…  I didn’t investigate the source to see if it uses “to_datetime” as opposed to “to_time”, but I’m assuming that it does, because of the following:

>> DateTime.tomorrow.to_time < DateTime.now.to_time
=> false
>> DateTime.tomorrow.to_datetime < DateTime.now.to_datetime
=> true

So what does Date#to_datetime do to screw us over?

>> DateTime.yesterday.to_datetime
=> Fri, 22 Aug 2008 00:00:00 0000
>> DateTime.tomorrow.to_datetime
=> Sun, 24 Aug 2008 00:00:00 0000
>> DateTime.now.to_datetime
=> Sat, 23 Aug 2008 23:28:11 -0400

Do you see it?  The answer is right there, but it’s easy to miss.  I missed it over and over again for about 40 minutes.  ”-0400” — the timezone.  The timezone had been screwing me up all along.  The DateTime object has my timezone from the get-go, but the Date objects were converted as UTC. Lovely… just lovely.

Now, I wasn’t the original author of the code.  Just an archaeologist.  My guess: the code worked when it was built (during business hours, not in the wee hours of the night when the timezones would trip them up), and it looked like the simplest thing needed.  Generally, you really can’t fault a developer for going that route. I certainly don’t.  But times and dates and especially anything related to the current time and date… well, these are special animals, and need to be dealt with special care.

The long and short of it?  Timezones are global environment state, and you need to be aware of it with any code (especially tests) that deal with time.  Avoid DateTime.yesterday or DateTime.tomorrow like the plague in your test/spec code (unless you enjoy tests that spuriously fail near the witching hour).  You should write your tests (and your production code) in such a way that you can simulate different timezones and different times of day in order to tease out bugs.  And if you need to compare or convert dates and times in your production code, be very aware of what time and timezone your business rules will require, especially if you have any Date objects that might be automatically coerced into DateTime objects.

You do realize that this completely plays into certain negative stereotypes of git, don’t you?  Passing a laptop around so that people can sign a patch/commit?  This seems to me like something a DVCS ought to make easy (easier than passing a laptop around).  Git core developers take more than a minute to figure out how to work with git send-email?  The fact that these things seem very “gitish” is evidence for some of git’s more negative stereotypes (some deserved, some not).

The article also mentions some much needed UI improvement to the index/cache workflow, and that sounds great.  I hope git continues to take a good critical look at some of its current UI decisions.

For the record, I prefer bzr, but I don’t hate git.  It’s a great and powerful piece of software, and has served the linux kernel and other Free/Libre/Open-Source projects tremendously.  It’s considerably better than svn or cvs for most open source projects, and it has some strengths that make it better than the other DVCS tools for certain projects.  But I do think it is over-hyped.  And I wouldn’t willingly inflict it upon myself for any personal project.  I personally think that most projects would be better served by one of the other open source DVCS tools: especially bzr (my VCS of choice), or hg.

Cool feature: say_with_time

If you find yourself putting comments around your code to explain to developers what’s going on, please consider instead using “say_with_time“.  Then you can document what is happening both in the code and on the console when the migration is actually running… and you’ll get other nice info printed out (like the elapsed time) as well.

Important feature: ActiveRecord::IrreversableMigration

If the migration cannot safely or easily be migrated downwards, then we need to communicate that clearly to other developers.  But “puts” isn’t good enough.  Instead, “raise ActiveRecord::IrreversableMigration“.

For complicated migrations, even if it is possible to safely reverse the migration, I strongly prefer simply raising the exception.  It’s too easy to make a mistake, and then you’ll have a DB that claims to be at one version, but has corrupted data for that version, which will most likely lead to more pain and suffering down the line.

If the migration is just cleaning up bad data, then there’s probably no real need to reverse it.  But in that case maybe you should at least print out a message to the screen letting the developer know that nothing is happening, and why that is okay.

Since I rarely ever use down migrations, my threshold is probably lower than most; if :Rinvert from rails.vim can’t automatically generate the down migration, then I will probably simply raise the exception.  I’ve personally witnessed too many needless bugs due to corrupted data and too many broken down migrations to invest any significant time into them.  At any rate, developers should use discretion with down migrations.

Oh, and please don’t ever run down migrations in production.  That’s what database backups are for, and you are backing up before you upgrade your production database, aren’t you?

Use the progressbar gem for long running data migrations

And one other thing that is not included with rails that you should probably be using anyway: the progressbar gem.  If you any long running data migrations, this is a must.  And just because it isn’t long running for you with your developer DB doesn’t mean it won’t be long running during deployment to production.  It’s trivially easy to use, and your deployer’s won’t be stuck wondering if their connection has been dropped or the migration has locked up.  And the ETA will let them know if they have time to get a cup of coffee.  The other developers and deployers will thank you.

Simple Example

(albeit, also a poorly contrived example)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

require 'progressbar'
 
class CreateWidgetAuxiliaryFrobs < ActiveRecord::Migration
 
  def self.up
    create_table :widget_auxiliary_frobs do |t|
      t.integer "widget_id"
      t.string  "frob_type"
      t.integer "frobitude"
      # etc...
    end
 
    say_with_time("migrating froms from widgets") do
      widgets = Widget.find(:all)
      pbar = ProgressBar.new("Generating Widget Frobs", widgets.size)
      widgets.each do |w|
       # this code changes the data irreversibly
       # this code can't be (easily) rewritten with a SQL UPDATE or INSERT
       # etc  etc  etc
       pbar.inc
      end
      pbar.finish
    end
 
    say_with_time("delete obsolete widget/wadgit data") do
      Wadget.delete_all("value = 'kerfluffle'")
      remove_column :widget, :foo
      remove_column :widget, :bar_id
      # etc...
    end
  end
 
  def self.down
    raise ActiveRecord::IrreversibleMigration
  end
end

If the dataset is very large

If the dataset is especially large, you’ll want to iterate through it in a less naive manner than I did above: “Widget.find(:all).each“.  At the very least, you’ll want to iterate in such a way that already handled objects can be garbage collected prior to the end of the loop.  This might be necessary to avoiding the dreaded NoMemoryError (or decreased speed due to massive swapping).  This can be handled simply by iterating through the dataset using pagination, but you could also employ a more sophisticated strategy.

First, anyone who claims that automated unit tests removes the need for QA testers or usability testing or any form of exploratory (manual) testing… they’re completely nuts.   Nor does it remove the need for code reviews, or refactoring, or paying attention to software design.  This seems to be main point of posts like like Hampton Hates Automated Testing and Luke Francl’s “Testing is Overated” talk at RubyFringe.  However, this is not a claim that I’ve ever heard any XPer, agilist or TDD/BDD proponent make. Instead, they’ve been saying for years now that “test driven development is not about testing”.  And talking about automated developer testing without talking about TDD/BDD seems to me like an adventure in missing the point.

If automated developer testing leads to undue confidence, then Hampton is correct: the developer’s hubris will allow more bugs to get through. In my experience, a humble/paranoid developer will benefit greatly from BDD and put out code with fewer bugs in less time. And an arrogant “my code doesn’t have bugs because of pet theory #462″ developer will eventually get themselves into trouble with or without automated tests… but the automated tests may help them dig out from it and perhaps not get into that particular brand of trouble again.

People who confuse automated developer testing with QA testing often talk about “bugs” and “reducing defect count” as if the main point of automated developer testing is to reduce bugs.  Test Driven Development is about driving yourself towards a better design (which is often also more easily testable as a happy byproduct).  This is why BDD (Behavior Driven Development) was coined: to help people grok TDD without being biased by the word “test” and some of its other connotations.  Several other terms were tried out (“eXecutable eXample Driven design” or “XXD” was my personal favorite), but BDD is the one that seemed to catch on and win out.

Also, BDD isn’t meant to be a “crutch” for “if you’re not good about thinking about programming.” It’s about giving all programmers, the so-so programmers and the guru programmers, another paradigm through which to view their code. BDD is about imagining the best possible API/interface/outcome, giving some example of how that code might work (if only the implementation were there), and then filling in the implementation until it works. And then doing it again in short incremental improvements. It’s about getting into “the flow” in minutes, instead of hours.

Yeah, those examples and their assertions also stay around until later as a regression suite. That’s nice. The better examples also hang around as documentation to future developers for how the system is expected to behave. That’s very nice. But, in my experience, they also allow me to develop better, cleaner code more quickly than otherwise… and the “tests” are both a happy byproduct and an enabler.

Honestly, the thought of me blogging sort of weirds me out.

The permanence of data on the internet is part of it, but that exists with emails to public mailing lists, and comments on other blogs, and even with IRC transcripts… and doesn’t bother me as much.  But blogging is more like, “this site here represents my thoughts”.  So I’m going to put up a disclaimer here: not only does this site not represent the opinions of my employers (past, present, and future), but it might not represent my own thoughts (past, present, or future).  I reserve the right to change my mind, and also to post incomplete thoughts which a part of me disagrees with.

It seems like the responsibility and formality are expected to be a notch up from other more informal communication media: how often one posts, how well they write, etc.  I suppose these things aren’t that big of a deal.  I don’t hold other blog writers to any particularly high standards in this realm.  But still, these thoughts tend to increase stress levels, and why would I willingly do that to myself?

Most importantly, I don’t really think that I will write anything that I personally would be interested in reading.  I don’t think I have anything particularly important to say.  And I don’t really care if people across the world are affected by what I say.  Again, this isn’t something that I judge other bloggers by.

So what will I write about?  When will I write?  And what will happen when (not if) I’m embarrassed by what I’ve written?  Enough naval-gazing… we’ll see what happens.