Ruby Best Practices

Ruby Mendicant University is a Go!

gregory.t.brown@gmail.com (Gregory Brown) — Fri, 04 Jun 2010 14:50:00 -0000

Born less than 24 hours ago, my Ruby Mendicant University idea is already more than a third of the way to having its initial costs covered. In less than 12 hours, we’ve had 35 people request a copy of the entrance exam. So now that the idea is validated, it’s time to begin on the execution.

You can keep up on the latest news by following the rubymendicant tag at seacreature.posterous.com

PS: This morning, I decided that I want to consolidate my blogging and tweeting, so most of my content will be posted to my new posterous blog rather than here at RBP blog. Also, I am moving my twitter account over to @seacreature exclusively, rather than using @rubypractices. While this isn’t quite an announcement of ending the RBP Blog project, it’s a step in that direction. Thanks so much for your attention and feedback over the last year or so. Hope to see you on the other side!

IDEA: Ruby Mendicant University

gregory.t.brown@gmail.com (Gregory Brown) — Thu, 03 Jun 2010 14:50:00 -0000

UPDATE: You can donate now at Pledgie / I know this is early, but in the spirit of Ruby Mendicant, I’m looking for those trusting individuals who will give with altruistic intentions first, I’ll spend my time convincing everyone else later :)

UPDATE 2: More details to come, but those who wish to receive a copy of the entrance exam should sign up via this google form.

Back in 2008, the highlight of my year was the Ruby Mendicant project. Through some stroke of luck, I ended up getting enough funding from independent community donations to take 22 weeks off of work to focus on building Prawn, a pure ruby PDF generation library that is now nearing its 1.0 release.

Now in 2010, I’d like to do the same thing for Ruby training and education. Similar to my original post that spawned Ruby Mendicant, the details are currently fuzzy in my head, but I have enough of a rough outline to collect some comments on.

The Idea

I want to run a free online school designed to help intermediate Ruby programmers master their craft. Each session would include up to 20 or so participants and run for 3 weeks.

The basic activities would include:

an entrance exam (basic coding problem and questionnaire)
selected readings in freely available Ruby books and online resources
individual and group code review
realistic problems to work on and discuss
Q&A sessions
a final exam (which if passed, would earn the student ‘alumni’ status)
possibly some pre-recorded or live presentations
a mailing list for students to discuss questions with me
online discussions with guest speakers from our community.

The goal would be to keep these classes going on a rolling basis, so that we could reach a large number of students in the course of a year. If we did a schedule like 3 weeks on, 1 week off, we could do 13 sessions in a year, allowing me to reach up to 260 students.

Of the available slots, I would also like to reserve a certain amount of them for “hardship” situations. People who are currently out of work, those who are in tough economic climates, or have some sort of difficulty in their lives that this opportunity could really help them overcome. I have not yet figured out how to do this without introducing a ton of bias in my selections, and I have no way of verifying these details, but it seems like a good idea in theory to me at least.

At least some of the sessions would be open to the community at large, and at least some of the material would be released under an open documentation license. This way, while the core focus would be on affecting big change for small groups at a time, the whole community could benefit from the existence of this program as well.

Funding

The up front cost of building the material is large, enough where I would need to take a couple days off a week from consulting work for a period of 8 weeks or so to come up with adequate material. While the replacement cost for that work is pretty high (over 6k), I could probably still get by well enough if I had about $3000 in donations to produce the initial material.

The promising thing about the above lesson plan is that since a lot of it is interactive and tailored to individual efforts, once I build the core lesson plan, actually running the “school” will be comparatively less work. I won’t know at all until I actually run it, but I would expect that I could keep the school up and running for about $1500 a month.

But in the Mendicant spirit, I only would want to keep this thing going if it was of value to the community. So rather than looking for donations for the running of the school up front, I would only raise money to cover the initial costs of content creation.

Whether the school lives or dies, grows or shrinks, would be based on the generosity of previous students as well as that of the community at large.

Schedule

If I could raise enough money by the end of June, I could then shift my schedule around in July and August to allow me to work on content creation. That would let me start the first class around the first week of September.

Why Me?

Besides the Ruby Mendicant project, I have also taught trainings at the Lone Star Ruby Conference (2008,2009), and am also part of the trio hosting The Compleat Rubyist. I have written two books that are now completely free for people to download and read. And other stuff.

Trust me. I’d be good at this :)

If you’re wondering what’s in it for me: I believe that free education is one of the most valuable things in the world, and I also learn a ton by teaching others. If I can make enough money to offset my costs and maintain a decent house-and-wife life, I feel like this is a super good use of my time.

What do you think?

Right now, feedback is key. I only want to take this project on if I think it’ll be a sure thing. Please respond, answering these questions:

Would you want to attend this online school?
Would you be willing to donate to help with its creation?
Would you recommend this program to others?
What can I do to make it even more awesome?

Thanks in advance for your suggestions. Here’s hoping that we can make this work :)

UPDATE 2: More details to come, but those who wish to receive a copy of the entrance exam should sign up via this google form.

If you want to see the wizard, go to Oz.

gregory.t.brown@gmail.com (Gregory Brown) — Wed, 21 Apr 2010 14:50:00 -0000

Back in June of 2005, I booked a flight out to Oklahoma City, OK, but it might as well have been to Oz. I was off to see the wizard who had been teaching me black magic in both Perl and Ruby throughout my high school days.

James Edward Gray II and I had somehow convinced Ruby Central, Inc. that a web game framework was worth a Codefest grant, and we used the money as a chance to finally meet each other in person. At the time, we decided to build things from scratch, since Rails 0.12 didn’t quite have the features we needed :)

Not counting the friends I talked into studying programming here and there, this was my first time ever working side by side with another hacker. I didn’t know what to expect, but by the time I left, I couldn’t believe that what we had done was possible. Safe to say, JEG2 blew my mind, in the way that any good wizard can. Here’s what I wrote just after returning home in June 2005:

The last nine days were amazing. Exploited undocumented features of WEBRick.
Making use of circular logic flows, making code do things that it wasn’t built
to do. Pushing the limits, building truly clever tools and libraries that will
make people’s lives easier, and more fun.

I myself feel like I’m standing a little taller after all the hard work we
did. That was hacking in it’s purest nature, and though I don’t like to self
attribute that word, there is nothing else to describe it. Ideas flowed any
hour of the day, even in our dreams. No one tried to take charge, I didn’t get
mad when James replaced bits of my code with something better, and James
didn’t get mad when I questioned his logic and pushed him to raise the bar. In
the rare occasion that I proved James wrong on something, he’d just shrug his
shoulders, embrace The Right Way, and go with it.

We joked around a lot referring to certain programming practices as “The way
of life”. Though that is quite silly when it applies to 80 character linewrap
or a certain tab width, it was something that motivated us. We could look at
our code, and at a glance see if it was following “The way” or not. When it
wasn’t, we waited for something better to come along, and then we did what we
had to do to make it happen.

Now, I was just a kid at the time, but I knew something important had just happened. Most importantly I realized that the kind of interaction you can have over the internet, though amazing, pales in comparison to face-to-face interaction. Here’s what James had to say shortly after our first meeting:

“We’ve just completed nine solid days of development on Gambit. Now
that’s a “Codefest” alright! I thought I would share a little with
the curious about how I think it went…

Greg Brown flew out to my home in Oklahoma so we could work on
Gambit. It was nice to finally meet face-to-face. We’ve actually
programmed together on many projects these last couple of years, but
this was the first time we didn’t do it over the Internet. We’re
both grateful to the wonderful people at Ruby Central for giving us
that opportunity.

We’ve had practice, so we work pretty well together by now. Greg
would probably say that I’ve almost beat all his bad habits out of
him. ;) True or not, I know he’s always challenging me and pushing
me to new limits of what I can build. I think we both learned a lot
from working together on this project.

While there is a certain amount of altruism involved in mentoring a novice, it is an act that pays you back tenfold. Every concept that you can teach another person is one that you must master through and through, in ways that you’d never even scratch the surface of on your own.

Whether he realizes it or not, James revealed a secret to me during that hackfest, one that is to blame for all of my future successes in programming: Share your experiences and knowledge with others, and you win.

Fast forward to 2010, and obviously JEG2 and I have come a long way. We’ve both done talks throughout the US, and James even made it over to Japan last year. We’ve both published books on Ruby, and made more friends in the community than we ever imagined possible back in 2005. While part of me feels indebted to James still, I feel like I’ve paid it forward through my works. That made our mentorship role turn into a friendly rivalry, where we both keep pushing each other to get better at what we do, even if indirectly.

James had a big head start, so he normally beats me to the punch on things. Up until recently, I had only one thing under my belt that JEG2 didn’t: I had helped design and run a Ruby conference. Not one to be outdone, JEG2 has decided to level that playing field by running Red Dirt RubyConf.

Red Dirt RubyConf: Your ticket to Oz

If you like what I’ve been doing in Ruby, you now know that I owe it all to JEG2. Here’s the good news: He’s now inviting all of you to his neck of the woods to spend some time hacking, learning, and sharing. But you need to act fast, registration closes Friday, April 23!

Red Dirt RubyConf is a unique two day conference which blends training in with a uniquely themed single track session lineup. In it, you won’t just get to meet James, but also some other amazing Ruby people as well, including Dave Thomas and Jim Weirich.

The conference is run by James, his lovely wife Dana (who I could write a whole other post about), and some other great folks from the Oklahoma Ruby group. If you head out there, I can promise you that you’ll have an awesome time, learn a ton, and meet some amazing people.

Unfortunately, I won’t be able to attend, but I’ll sure be there in spirit. If you do make it there, tell James I said hi, and have a great time!

DISCLOSURE: I told James I’d be writing something to promote Red Dirt, but he didn’t ask me to do this, and he had no idea what I’d come up with. So I take 100% responsibility for the contents of this article.

rubyproblems.com is now live!

gregory.t.brown@gmail.com (Gregory Brown) — Wed, 07 Apr 2010 14:50:00 -0000

Back on St. Patrick’s day, I had made the following plug about rubyproblems.com at the bottom of my last post:

This site will provide realistic exercises that test your Ruby and general coding skills, along with detailed tutorials written in the style of RBP explaining possible solutions to the problems. The exercises will be free and open to everyone, the solutions we’ll be selling as nicely typeset, professionally edited, DRM-free PDF download

I am pleased to announce that this service did indeed launch yesterday, and that you can give it a try by heading over to rubyproblems.com now. If you need a bit more information, consider checking out this screencast or this announcement.

While this is still a bit of an experiment for us, we’re really excited to see how things turn out. Those who liked my book should love this site, which is why I’m announcing it here.

But now, the RBP blog should return to its non-marketing-hype self. In fact, I really want to find the time to write about why I think this is the most horrible syntax ever:

describe Array do
  its(:length) { should == 0 }
end

But I suppose that bit of flame bait will need to wait until a later day :)

Full Book Now Available For Free!

gregory.t.brown@gmail.com (Gregory Brown) — Wed, 17 Mar 2010 16:50:00 -0000

The last few weeks have been a wild ride. Starting in January, I’ve been releasing a chapter at a time here on the RBP blog, and many of those chapters were pretty well commented on. Just for the sake of completeness, here’s a link back to each of those posts:

At this point, I’d like to invite you to just grab the whole thing and read it at your leisure. This includes the final chapter “Skillful Project Maintenance”, as well as the three appendixes: “Writing Backwards Compatible Code”, “Leveraging Ruby’s Standard Library”, and “Ruby Worst Practices”.

Since the book is now open source, if you find something you don’t like about it, it’s your responsibility to help make it better! But if you do like it as it is, it might be more pleasant to read in print or on your Kindle, so you might want to pick it up from O’Reilly or Amazon.

Manuscript and Production Files

You can find the details about the manuscript and production files on github, now released under a Creative Commons license. It might be a little while before I can put some time into making this contributor friendly, but those looking to experiment or explore a bit are certainly welcome. The manuscript is written using the amazing asciidoc toolchain, which means the plaintext files you see in the git repository actually are what I used to generate something very close to the final print version of RBP.

So that’s pretty much it. While this will soon mark a new beginning, this figuratively and literally marks the last chapter in the history of RBP being “my book”. It’s yours now, do what you want with it. If you have interesting ideas that you want to run by me, I’d be happy to help however I can. Otherwise, enjoy and have fun!

But I finished the RBP book and I want more! What should I do?

Okay, you got me. I’ve been trying to take the “spirit” of RBP and apply it to two new projects, both a little more interactive in nature. For those who enjoyed the book, you may be interested in these two resources, both on the horizon.

The first is rubyproblems.com. This site will provide realistic exercises that test your Ruby and general coding skills, along with detailed tutorials written in the style of RBP explaining possible solutions to the problems. The exercises will be free and open to everyone, the solutions we’ll be selling as nicely typeset, professionally edited, DRM-free PDF downloads. We launch April 6th, 2010, but if you register now, you’ll get a free solution download when the site goes live. Whether you plan on buying content or not, the exercises themselves should provide great learning opportunities. If you liked RBP, you’ll definitely like Ruby Problems.

The second chance to bolster what you’ve learned in RBP is to attend a Compleat Rubyist training event. This is a joint venture between David A. Black, Jeremy McAnally, and myself that’s designed to provide a crash course in going from “knowing Ruby” to “being awesome at Ruby”. We did one of these in Tampa, FL in January, and it was blast. Our next one is scheduled for the Chicago area on June 18-19. We plan to do this as a regular thing, so if you can’t make it out to the Midwest, let us know where we should be going to find you! If you want a little more detail, you can check out my RubyTalk announcement about the upcoming event, and perhaps take a look at the Tampa retrospective here on the RBP blog.

Disclaimer

While I typically hate direct marketing, I am absolutely excited about the above two things, and so I felt compelled to mention them as good ‘next steps’ as you go beyond RBP. Doing these as commercial projects won’t ever make me rich, but it does allow me to take time away from billable work and really focus on producing awesome content and engaging with those who could learn something from it. So just know that whenever you send a bit of cash my way, you’re supporting a fellow hacker who will keep giving back at every opportunity.

But for those a bit weary of marketing gimmicks, the RBP blog will be going back to its pristine “no fluff, just stuff” program after today. It is a little hard to keep new content flowing, but we’ll do the best we can. Until then, happy hacking!

Ruby Tuesdays: RBP Chapter 7

gregory.t.brown@gmail.com (Gregory Brown) — Tue, 09 Mar 2010 14:00:00 -0000

If you’re reading this blog, you probably know that the Ruby Best Practices book exists. Even if you haven’t read it, you might have a sense for the sort of topics we cover based on the content you’ve seen on this blog. But now, everyone is going to get a chance to read RBP the way its meant to be read: as a conversation.

Progress To Date

We’ve already released the first five chapters, and discussion has been great. Be sure to check out these previous posts if you haven’t already:

Chapter 1: Driving Code Through Tests

Chapter 2: Designing Beautiful APIS / Chapter 3: Mastering the Dynamic Toolkit

Chapter 4: Text Processing and File Management

Chapter 5: Functional Programming Techniques

Chapter 6: When Things Go Wrong

These discussions should give you a sense of the wide range of ideas our readers have been sharing as a result of this ongoing book study.

How To Read RBP

Readers are encouraged to fight RBP as they read it, rather than just soaking up the information. Although I claim this book is about “Best Practices”, the only reason that is true is that it’s a result of countless conversations with folks who are deep in the Ruby trenches getting stuff done. The only way for RBP to remain current and relevant is to continue these discussions, using its content as a jumping off point for fresh ideas.

Today’s Topic

In 2010, programmers no longer have an excuse for not having a baseline understanding of multilingualization and localization techniques. But for those who have not yet taken a crash course, this chapter on “Reducing Cultural Barriers” provides a primer that should be good enough to get you started.

Go ahead and download Chapter 7 now. You’re encouraged to participate in the discussion here once you’ve had a chance to play with some of the ideas from the book. Don’t worry if it takes you more than a few days finish reading it, you can come back and comment any time.

Enjoy, and come back next Tuesday (2010.03.16) for the final chapter, “Skillful Project Maintenance”, which covers Ruby’s built in project management tools, and some of the techniques surrounding them.

For Your Consideration

O’Reilly is being really nice to me by letting me give away my book, especially considering that I haven’t quite cleared my advance yet (though I’m getting closer now, finally!)

If you like what you see, please buy the book. You can get it directly from the publisher or via amazon. I imagine that seeing decent sales numbers will encourage O’Reilly to keep moving towards making their content openly available, which would totally rock.

For those wishing to do interesting things with this material, note that it is released under the Creative Commons NC-SA license. This will become immensely more useful once the source documents for the manuscript are posted in late March, but if you’ve got any questions at all about this, you can ask me, and I’ll ask my publisher, and we’ll get back to you.

Ruby Tuesdays: RBP Chapter 6

gregory.t.brown@gmail.com (Gregory Brown) — Tue, 02 Mar 2010 07:00:00 -0000

Progress To Date

We’ve already released the first five chapters, and discussion has been great. Be sure to check out these previous posts if you haven’t already:

Chapter 1: Driving Code Through Tests

Chapter 2: Designing Beautiful APIS / Chapter 3: Mastering the Dynamic Toolkit

Chapter 4: Text Processing and File Management

Chapter 5: Functional Programming Techniques

These discussions should give you a sense of the wide range of ideas our readers have been sharing as a result of this ongoing book study.

How To Read RBP

Today’s Topic

This chapter on what to do “When Things Go Wrong” turned out to be one of the most enjoyable ones to write. Having a strong ability to troubleshoot and debug code is a powerful skill to have, and I do my best to share all my secrets here.

Go ahead and download Chapter 6 now. You’re encouraged to participate in the discussion here once you’ve had a chance to play with some of the ideas from the book. Don’t worry if it takes you more than a few days finish reading it, you can come back and comment any time.

Enjoy, and come back next Tuesday (2010.03.09) for Chapter 7, “Reducing Cultural Barriers”, which covers multilingualization (m17n) and localization (L10n) techniques.

For Your Consideration

O’Reilly is being really nice to me by letting me give away my book, especially considering that I haven’t quite cleared my advance yet (though I’m getting closer now, finally!)

If you like what you see, please consider buying the book. You can get it directly from the publisher or via amazon. I imagine that seeing decent sales numbers will encourage O’Reilly to keep moving towards making their content openly available, which would totally rock.

Ruby Tuesdays: RBP Chapter 5

gregory.t.brown@gmail.com (Gregory Brown) — Tue, 23 Feb 2010 15:00:00 -0000

Progress To Date

We’ve already released the first four chapters, and discussion has been great. Be sure to check out these previous posts if you haven’t already:

Chapter 1: Driving Code Through Tests

Chapter 2: Designing Beautiful APIS / Chapter 3: Mastering the Dynamic Toolkit

Chapter 4: Text Processing and File Management

These discussions should give you a sense of the wide range of ideas our readers have been sharing as a result of this ongoing book study.

How To Read RBP

Today’s Topic

If you’re willing to participate in the discussion afterwards, go ahead and download Chapter 5 now. Don’t worry if it takes you more than a few days finish reading it, you can come back and comment any time.

This chapter was supposed to be my “fun” topic, but turned out to be more practical than I expected. I had originally started out writing about how to do functional programming in Ruby, but later realized that was an incredibly bad idea. Ruby isn’t a great functional programming language, but certain functional programming techniques do still pay off. This chapter is about those techniques.

Enjoy, and come back next Tuesday (2010.03.02) for Chapter 6, “When Things Go Wrong”.

For Your Consideration

O’Reilly is being really nice to me by letting me give away my book, especially considering that I haven’t quite cleared my advance yet. So if you like what you see, and want to be able to read it all now instead of waiting several more weeks for it, please consider buying the book. You can get it directly from the publisher or via amazon. While I do make a little more money when you buy from O’Reilly, I wasn’t expecting to get rich off of RBP, so don’t feel bad buying the discounted copies from Amazon. But I’m pretty sure that seeing a spike in sales would encourage them to do more open source books, so… keep that in mind.

For those wishing to do interesting things with this material, note that it is released under the Creative Commons NC-SA license. This will become immensely more useful once the source documents are posted in late March, but if you’ve got any questions at all about this, you can ask me, and I’ll ask my publisher, and we’ll get back to you.

Ruby Tuesdays: RBP Chapter 4

gregory.t.brown@gmail.com (Gregory Brown) — Tue, 16 Feb 2010 15:00:00 -0000

Progress To Date

We’ve already released the first three chapters, and discussion has been great. If you haven’t seen them already, check out the first week’s discussion on testing, and then head over and look at the double header on API design and metaprogramming. These discussions should give you a sense of the wide range of ideas our readers have been sharing as a result of this book study.

How To Read RBP

Today’s Topic

If you’re willing to participate in the discussion afterwards, go ahead and download Chapter 4 now. Don’t worry if it takes you more than a few days finish reading it, you can come back and comment any time.

While chapters 2 and 3 were about somewhat subtle features, this chapter is as concrete as they come. Those with some Perl blood in them should find it familiar, as it’s all about how to munge text and move stuff around on your filesystem. But those who struggle with the scripting side of Ruby should find a number of techniques that will make their job easier.

Enjoy, and come back next Tuesday (2010.02.23) for Chapter 5, “Functional Programming Techniques”.

For Your Consideration

For those wishing to do interesting things with this material, note that it is released under the Creative Commons NC-SA license. This will become immensely more useful once the source documents are posted in late March, but if you’ve got any questions at all about this, you can ask me, and I’ll ask my publisher, and we’ll get back to you.

RBP is useless without you

gregory.t.brown@gmail.com (Gregory Brown) — Fri, 12 Feb 2010 05:24:00 -0000

UPDATE 2010.02.13: Lots of folks have taken the initiative to comment after reading this, and others have pointed out that they indeed need more time before they can comment. But since people seem generally interested in seeing Ch4 sooner rather than later, I’ll release it on Tuesday. Coincidentally, there is a great post I found on HN that does a better job than I did summarizing how tech books (especially RBP) ought to be read. If you haven’t seen it yet, go read Kenjitsu.

Since I’ve posted the first three chapters, my amazon ratings have gone way up, and I’ve seen lots of people mention the book on twitter. This is great for marketing, but as you may know, I care much more about the actual content here.

Things started out great! We had an awesome discussion about testing two weeks ago and I expected to see the same on APIs and metaprogramming. But as it turned out, only two brave souls offered up their thoughts, even though lots of people downloaded the content. That was a big disappointment to me, and now I’m trying to guess at what went wrong.

One possibility is that I’ve oversaturated folks, so I’m giving everyone an extra week to comment on Ch2-3 before I put out the “Text Processing and File Management” chapter. Hopefully, by next Friday we’ll have a good discussion going there, and the Ch4 release will just keep the ball rolling.

But far more grave, is my fear that some folks might be too timid to express their thoughts about the material, perhaps because it’s in book form rather than written up in some generic blog post. This to me, is exactly what will prevent them from getting anything worthwhile out of my book. So if you’ve been holding back comments just because you didn’t want to challenge RBP’s “bookiness” out in the open, please don’t. I can handle all sorts of criticism, and the book will benefit as a result of it.

I am very serious about the idea that “Best Practices” really don’t have much value in a vacuum. I’m certain that the benefits that my book can offer its readers are maximized in open conversation. This is why I made sure to build an eventual open content licensing into RBP’s contract, and why I’m releasing free chapters now.

RBP is useless without you, so please, participate.

Weekend Reading: RBP Chapters 2-3

gregory.t.brown@gmail.com (Gregory Brown) — Fri, 05 Feb 2010 14:00:00 -0000

If you missed last week’s post, which introduces chapter 1, you’ll want to check that out. There was some great discussion among readers that add a lot to what I had to say in the book. I expect we’ll see the same thing happen this time around.

Today’s Topics

This week, I’m releasing two chapters, Designing Beautiful APIs and Mastering the Dynamic Toolkit. Incase the latter sounds familiar, it is indeed the book’s sample chapter. But it also happens to be my favorite chapter in the book, so I didn’t want to skip over it without a chance for discussion.

So remember, if you click those links, your responsibility is to participate in the discussion here by offering up your thoughts about what you’ve read. Best practices cannot be rules that are simply absorbed and followed if they are to be of any use… instead, they must be extracted from and influenced by those who work with the real problems that they are meant to solve.

It would be great to hear your experiences with the topics these chapters cover, even if they’re not directly related to the book content.

For Your Consideration

O’Reilly is being really nice to me by letting me give away my book, especially considering that I haven’t quite cleared my advance yet. So if you like what you see, and want to be able to read it all now instead of waiting eight weeks for it, please consider buying the book. You can get it directly from the publisher or via amazon. While I do make a little more money when you buy from O’Reilly, I wasn’t expecting to get rich off of RBP, so don’t feel bad buying the discounted copies from Amazon. But I’m pretty sure that seeing a spike in sales would encourage them to do more open source books, so… keep that in mind.

For those wishing to do interesting things with this material, note that it is released under the Creative Commons NC-SA license. This will become immensely more useful once the source documents are posted in late March, but if you’ve got any questions at all about this, you can ask me, and I’ll ask my publisher, and we’ll get back to you.

Anyway that’s all for now, enjoy the chapters and let me know what you think!

Weekend Reading: RBP Chapter 1

gregory.t.brown@gmail.com (Gregory Brown) — Fri, 29 Jan 2010 14:32:00 -0000

For the next 8 weeks, I will post a chapter from RBP every Friday. You don’t need to pay me a cent if you download it, but what I do want you to do is leave a comment here sharing your thoughts once you’ve finished reading. This way, we can use RBP’s content as a jumping off point for conversation, rather than treating it like some sort of static rulebook. Through this process, we can discover what our common practices really are. Over time, I will incorporate these ideas back into the manuscript, helping to keep the book up to date and relevant.

Today’s Topic

The first chapter I am releasing is Driving Code Through Tests, which covers a number testing philosophies and techniques. It aims to be framework agnostic, but leans on the Test::Unit API for its examples. The core idea of this chapter is to expose folks to the “spirit” of testing, rather than just the mechanics of it.

Upon re-reading this chapter in the winter of 2010 having written it in the spring of 2008, there are definitely a couple things I think differently about now. But as it turns out, I was more surprised by how much hasn’t changed, and how well this chapter seems to have stood the test of time. Of course, you may disagree, and I encourage you to tell me so if that’s the case. :)

Ready to get started? Go ahead and download the chapter now. Remember, if you click that link, I’m expecting you to post back here with your thoughts (or alternatively, write a response on your own blog and send me a link). If you find a technical error, you can report it via Github issues.

For Your Consideration

O’Reilly is being really nice to me by letting me give away my book, especially considering that I haven’t quite cleared my advance yet. So if you like what you see, and want to be able to read it all now instead of waiting eight weeks for it, please consider buying the book. You can get it directly from the publisher or via amazon. While I do make a little more money when you buy from O’Reilly, I wasn’t expecting to get rich off of RBP, so don’t feel bad buying the discounted copies from Amazon. But I’m pretty sure that seeing a spike in sales would encourage them to do more open source books, so… keep that in mind.

For those wishing to do interesting things with this material, note that it is released under the Creative Commons NC-SA license. This will become immensely more useful once the source documents are posted in late March, but if you’ve got any questions at all about this, you can ask me, and I’ll ask my publisher, and we’ll get back to you.

Anyway that’s all for now, enjoy the chapter and let me know what you think!

Reflections from "The Compleat Rubyist"

gregory.t.brown@gmail.com (Gregory Brown) — Mon, 25 Jan 2010 15:36:00 -0000

Ever since 2005, I’ve been attending and speaking at Ruby events. But the one thing I always wanted to do was run training sessions. Thankfully, over the last couple years, LSRC has allowed me to get my feet wet — but only as one of many excellent choices in a lineup of Ruby’s best and brightest. Until last weekend, I had never participated in professional training event that stood on its own.

What eventually became “The Compleat Rubyist” training, was originally an idea for “The Compleat Rubyist” book promotion. Jeremy McAnally, David A. Black, and myself have all written Ruby books, and they seem to compliment each other well. But in doing this, we realized that it would be more valuable, and more fun, to bring our show out on the open road rather than package it up in a box set.

Thus, our training event was born, and we set our sights on Tampa, FL for its first incarnation.

The Training

Instead of having a linear, specific set of bullet points to teach from, we broke our training into four half-day sessions that are representive of some of the most important topics in the Ruby ecosystem. This gave us a lot of leeway to adjust our materials and discussions based on individual student needs. The topics we picked were “Ruby Versions and Implementations”, “Metaprogramming”, “Testing”, and “Style and Substance”. Though these may seem a bit amorphous on first sight, they do a pretty good job of covering four key topics that a budding Rubyist must understand and come to appreciate.

Here are just a few thoughts from each of the modules, after seeing how things played out in class.

Ruby Versions and Implementations

One of the main things that keep people from trying out the alternative Ruby implementations and the various versions of Ruby is that they’re understandably afraid of messing up their systems. So David took a three-pronged approach to helping students overcome that fear.

The easiest stepping stone, perhaps, was to use ruby-versions.net. This great resource (maintained by David), lets you try out all sorts of ruby versions and implementations via a shell account so that you don’t need to worry about touching anything on your own machine. While this isn’t meant to be a long term solution, it’s probably the easiest way that you can try out pretty much any version of Ruby without having to go hunt down, install, and configure their packages.

In addition to this, David showed folks how to make use of multiruby (a tool that’s part of ZenTest). My favorite example of the whole day was one showing that using Ruby 1.8.7, it’s possible to write code that works on neither 1.8.6 nor 1.9.1, which lead into a whole other interesting discussion:

  $ multiruby -e "p 'hello'.map(&:upcase)"

  VERSION = 1.8.6-p388
  CMD     = ~/.multiruby/install/1.8.6-p388/bin/ruby -e p 'hello'.map(&:upcase)

  -e:1: wrong argument type Symbol (expected Proc) (TypeError)

  RESULT = pid 3988 exit 1

  VERSION = 1.8.7-p249
  CMD     = ~/.multiruby/install/1.8.7-p249/bin/ruby -e p 'hello'.map(&:upcase)

  ["HELLO"]

  RESULT = pid 3991 exit 0

  VERSION = 1.9.1-p378
  CMD     = ~/.multiruby/install/1.9.1-p378/bin/ruby -e p 'hello'.map(&:upcase)

  -e:1:in `<main>': undefined method `map' for "hello":String (NoMethodError)

  RESULT = pid 3995 exit 1

  TOTAL RESULT = 2 failures out of 3

  Passed: 1.8.7-p249
  Failed: 1.8.6-p388, 1.9.1-p378

We also took a look at rvm , which is another neat tool for managing multiple Ruby versions. While not necessarily a tool for every possible need, it is a very easy way of managing multiple rubies side by side without trashing your system-wide configurations.

Between these three tools, the students ended up with all they needed to explore the different implementations and versions for themselves. But that was really just the beginning. David then went on to discuss the various peculiarities across the board, and was sure to discuss where certain implementations or versions excel, and where they fall behind.

I’m happy to say that while very few of the students in our class had even tried Ruby 1.9 before our training, every one of them had the opportunity to do so before this session ended.

Meta-programming

At one point in time, everyone using Ruby thought meta-programming was some sort of magic. But in a post-Rails world, it is increasingly easy to help folks understand that all of this “voodoo” we do is really just making use of public method calls provided by Ruby objects that allow you to modify Ruby itself. Once a decent understanding of Ruby’s object model is established, all of the rest of the puzzle pieces just seem to fall into place.

This session had a lot of great discussions, and several exercises to encourage students to actively learn the tricks of the trade. Along the way, we stumbled across this interesting distinction between undef_method and remove_method:

  class A
    def foo
      "bar"
    end
  end

  class B < A
    def foo
      "baz"
    end

    remove_method :foo
  end

  class C
    def foo 
      "bar"
    end
  end

  class D < C
    def foo
      "baz"
    end

    undef_method :foo
  end

  p B.new.foo # "bar"

  p D.new.foo # raise NoMethodError

Testing

Fortunately, virtually all of our students had experience with test driven development of some sort or another. I think that’s a big difference between the Ruby ecosystem today and of say, 5 years ago. But similar to versions and implementations, there are so many choices out there that it’s hard to know what’s what. Jeremy kicked off this module with a state of the union address, breaking down the various different philosophies and toolchains there are out there, and what each of them bring to the table.

Once we got people thinking about the different options for testing out there, we decided to give them a glimpse behind the curtain to realize just how non-magical testing could be. To do this, we demonstrated not one, but two minimal testing frameworks that we built in less than a page or two of code to demonstrate the key concepts. While neither of these tools would be sensible to use in production, they both show how non-magical a test runner is under the hood.

Finally, David gave an open ended testing exercise that was a big hit. Pizza came, but some of our students ignored it until we reminded them to take a break. Many kept working on through lunch, all pairing together and actively discussing all sorts of language questions that went far beyond the scope of the exercise.

Style and Substance

This was my topic, and it went way better than I could have expected it to. I had a lot more content prepared than what I ended up getting to, mainly because we decided to collect some of the open questions that had come up in class and discuss those before running our scheduled content. The infamous class variable problem was discussed in great detail, and while I thought I had mastered their weaknesses, I even managed to mess up one of my assumptions about their behavior. Incase you’ve never been exposed to this fun before:

  class A
    @@foo = "from A"
  end
   
  class B < A
    @@foo = "from B"
  end
   
  # What's the value of @@foo in A now...?
   
  class A
    puts @@foo
  end
   
  # => from B
   
  # They're shared up the hierarchy?? BOOOO!!!
  # What's even worse? This ->
   
  class C
  end
   
  class D < C
    @@bar = "Magically different..."
  end
   
  class C
    @@bar = "And delicious."
  end
   
  class D
    puts @@bar
    # => Magically different...
  end
   
  class C
    puts @@bar
    # => And delicious.
  end
   
  # ZOMG THEY'RE NOT SHARED NOW.

Of course, the only sensible style advice here is to not use class variables at all, and since class instance variables can do the job just as well, that’s not really a big deal. We discussed how to do that, and then moved on to the regularly scheduled content.

I’m not sure whether we had an especially strong set of students or if people are just starting to “get” basic Ruby style idioms, but based on the first day and a half, it was evident that our students didn’t need to be told these basic things. Instead, I talked about “Ruby Style and Substance” at a more philosophical and design-oriented level, which is where I think our community tends to be weakest. Without giving too much away, a lot of my examples stemmed from discussions we’ve been having about refactoring Prawn before it’s 1.0 release, so you can check out our mailing list for a whole bunch of interesting design discussions if you want access to some of the raw materials I used for this session.

In the end, we gave everyone a chance to try their hand at basic API design for a fictional library we cooked up. I’m proud to say that every one of our students produced something that would be passable in an open source project. Ideally speaking, I’d like to say some of them took inspiration from what they learned in class, but no matter how they ended up there, I’m happy to see people writing code that looks like it comes from Ruby. This is especially encouraging considering that every one of our students came to Ruby after Rails was popularized.

The Event

We wanted “The Compleat Rubyist” to be not just a training, but an “event” as well. Because we were trying to keep registration costs low, we didn’t have much officially scheduled for this, but Tampa.rb really helped us pull through. Folks congregated at the nearby bar and restaurant Bahama Breeze from the time class ended until late into the evening Friday night. It was nice to have a mixture of students from the training and locals who just stopped by to hang out and say hi. I can honestly say that the sort of conversations I was having that night were on par with any I’ve had at the various conferences I’ve been at, but without all the associated commotion.

Pizza lunch on Saturday was a great way for us to leave a large chunk of semi-unscheduled time to discuss whatever topics students had on their mind. With a relatively small class size, I was able to get to know a number of the attendees, unlike my experience at most conferences these days.

While I expected to have a good time, I ended up having a blast. Based on my discussions with Jeremy and David, and the feedback from our students, I gather most others did as well.

The Future

While the Tampa, FL Compleat Rubyist event is now a thing of the past, we’re already thinking about how we can bring this session to other places. I was a little worried before the event that I wouldn’t want to just go somewhere else and do the same show, but now I know that every one of these is going to be different, since so much of the content was based on interaction with our attendees.

So, if the stuff I’ve said here interests you, you should follow compleatrubyist on twitter. We used our account actively during the event to share various little tips, and probably will continue to do that over time. But that’s also the place where you’ll see announcements about upcoming events, or ask us any questions you might have.

While I don’t typically like to use this blog for active marketing, I can honestly say that “The Compleat Rubyist” was a lot of fun, and that I think our students learned a ton. If folks like these summaries, I’ll try to get one out after each event. But it will be more fun, of course, if you come join us!

Learning From Bad Ideas

gregory.t.brown@gmail.com (Gregory Brown) — Sun, 22 Nov 2009 22:57:00 -0000

When we know something is ugly or “evil”, we’re quick to replace it with what we know to be a better solution. But if we don’t know why the solution is better, it makes it hard for us to investigate those things that look reasonable on the surface, yet have weaknesses just beneath the skin.

I’ll run through a quick example of what I mean, and then, it’ll be your turn to run with it and report back here. While I don’t use this approach all the time, I find it’s a neat tool to have handy when you’re trying to push your understanding of your code just a little bit farther.

Continuations are Evil?

It’s pretty common knowledge that continuations in Ruby are evil. But let’s pretend we didn’t know that. We might end up catching ourselves writing code like this:

  table.each do |row|
    call_cc do |next_row|
      row.each do |field|
        if field.valid?
          do_something_with(field)
        else
          STDERR.puts "skipping a bad row"
          next_row[]
        end 
      end
    end
  end

The continuation approach actually doesn’t look so bad. All we’re doing is iterating over a two-dimensional structure and skipping ahead to the next row if there is a problem with any of the fields. But having to pass along the next_row callback seems a bit heavy handed, and also makes one wonder what sort of magic it might be concealing. Preserving the same basic flow, we could be using catch / throw instead, lowering the conceptual baggage:

  table.each do |row|
    catch(:next_row) do
      row.each do |field|
        if field.valid?
          do_something_with(field)
        else
          STDERR.puts "skipping a bad row"
          throw :next_row
        end 
      end
    end
  end

So, now, we have something that looks more-or-less like a transactional block, which gets aborted when you throw :next_row. Not too bad, but if you’re like me, you probably get annoyed about having your eyes bounce up and down while you trace the flow, in both of these examples. We can fix that, of course:

  def process(row)
    row.each do |field|
      if field.valid?
        do_something_with(field)
      else
        STDERR.puts "skipping a bad row"
        return
      end
    end
  end
  
  table.each { |row| process(row) }

Now this is more like it! This code is probably the same as what a beginner might write, but it’s also the clearest out of what we’ve seen here. But without it as a point of reference, neither the catch / throw or callcc solutions would look terrible.

Through this quick little set of examples, I found a good reason not to use continuations for this particular use case. Arriving back at a simple solution by starting with a “clever” one and reducing it down to the fundamentals was a refreshing experience for me.

Your Homework

Now it’s your turn. I’m encouraging you to ignore “Best Practices” and the common idioms that we often accept as gospel.

Pick one technique that’s typically considered a no-no and do the best you can to use it in a somewhat reasonable way. You don’t want to waste your time with something that not even the most muddy-eyed coder would touch with a ten-foot pole, as you won’t learn much that way. Instead, work with something that looks fine or even clever at a first glance.

Then, try to fix up what you built by using more idiomatic, simpler code. Your goal is to create something that still looks good, but isn’t as much as a liability (conceptually) as what you started with. If you fail to do so, the worst thing that could happen is that you may have come across a new idiom worth sharing with others. But more likely, with a little effort you’ll have no trouble uncovering the wisdom behind whatever idiom you were putting to the test.

What’s the difference? Now, something that used to be a somewhat arbitrary rule to you is now common sense. As contexts shift, you may need to conduct new experiments, but repeat this exercise often enough and you’ll start to see a powerful intuition develop that allows you to internalize your design decisions rather than running through a punch list of patterns. And at least for me, I find that experience a lot more fun. I hope you will, too.

If you try out this exercise, please share what you’ve done, either via a link to your own blog, or a gist. I’m interested in how many bad ideas we can rack up here. :)

Be Nice and Have Fun

gregory.t.brown@gmail.com (Gregory Brown) — Fri, 21 Aug 2009 11:25:00 -0000

Yet again, we’re experiencing a firestorm that will shake things up and change the Ruby community in a big way. But like anything else, the best thing we can do is remember that the sky is not falling, and that all internet drama is ephemeral at best.

Sure, we’ll all dearly miss a valued community member who inspired many of us. But thanks to distributed revision control systems, we’ll be able to commemorate _why through his works, currently being mirrored on github .

So what do we do in this post _why world? The answer to that is fairly simple: the same thing we’ve been doing. The true spirit of the Ruby community (and even the free software hacker community at large) is to work on fun stuff, and try to be nice to people. If we can keep that up, the sky will not fall, and may even make room for new stars to light up the present darkness.

I’ll let this brief statement stand on its own here, as RBP has no intentions of becoming a gossip blog, but feel free to leave your thoughts in the comments.

Expect a new Ruby 1.9 series post some time before or just after LSRC. Until then, keep your heads up folks.

NOTE: I have Aaron Patterson to thank for expressing what I was thinking in words ‘do fun stuff and try to be nice’

Should I Tap that Hash? (Ruby 1.9 Style)

gregory.t.brown@gmail.com (Gregory Brown) — Wed, 05 Aug 2009 12:00:00 -0000

UPDATE: Be sure to read the comments. I’ve already learned a lot from them, and you might, too.

Though the Ruby Best Practices book covers Ruby 1.9, it is decidedly not a “Ruby 1.9 Best Practices” book. The reason for this, of course, is that common idioms for Ruby 1.9 haven’t evolved yet.

Let’s work together to change that. Every week until Ruby 1.9.2 comes out, I’ll be coming up with short, manageable bits of Ruby 1.9 code for discussion, as part of a “Ruby 1.9 Style” series. These should not be taken to be authoritative in any way, but instead work as conversation starters so that we can move forward as a community and separate the good from the bad when hacking code on Ruby 1.9.

Rather than describing in detail how this series will work, I’ll just begin with some real content and you can get a sense of the format from that. The only key thing is to remember to not be lazy, and to actually comment on these posts. Ruby 1.9 is basically the wild west right now, and its going to take quite a few sound voices to tame it. So be sure to share your thoughts after you take a look at the proposed idiom below.

Object#tap, a seemingly benign addition.

Ruby 1.9 gives us tap. And tap is sort of neat because it can be useful as a debugging tool, especially in chained code.

  >>  [1,2,3].map { |x| x + 1 }.tap { |y| p y }.inject(:+)
  [2, 3, 4]
  => 9

There isn’t much conceptual weight here, either. Essentially, you’re looking at something like this:

  def tap
    yield(self)
    self
  end

But hmm, doesn’t that look familiar?

Object#tap as an alternative to ActiveSupport’s returning

Those who work with Rails or with ActiveSupport in some other capacity will have seen returning. The problem it is meant to solve is seen in the code below.

  def ugly
    results = {}

    [:x, :y, :z].each do |letter|
      results[letter] = rand(100)
    end

    results
  end

Using returning, this can be cleaned up a bit:

def sexy
  returning({}) do |results|
    [:x, :y, :z].each do |letter|
      results[letter] = rand(100)
    end
  end
end

This code ~~is definitely more DRY, and~~ looks pretty clean. The only problem with it is that since it relies on ActiveSupport, you’re essentially sifting through DHH’s junk drawer for a piece of non-standard functionality for a fairly basic purpose. While it may not be a “Rails Best Practice”, I tend to shy away from this sort of thing to keep from being too dependent on a framework that I only use part of the time.

But if we think for a second, how would returning be implemented? Something like this, right?

  def returning(obj)
    yield(obj)
    obj
  end

Go check out the end of the previous section. What we can see now is that returning is just Object#tap inside out! So what happens when we use tap that way? Let’s take a look.

Tapping that Hash.

I’ve started on a few Ruby 1.9 production apps, and that’s where I first ran into attempting to use tap as if it were returning. Take a look at this bit of code:

  def times_for_period(date)
    days = work_days_for_period(date)
    regular_hours_by_week = Hash.new(0)

    { :regular_hours => 0, :other_hours => Hash.new(0) }.tap do |results|
      days.each do |d|
        times = d.times

        results[:regular_hours] += times[:regular_hours]
        regular_hours_by_week[d.date.cweek] += times[:regular_hours]

        times[:other_hours].each { |k,v| results[:other_hours][k] += v }
      end

      results[:weekly_hours] = regular_hours_by_week.keys.sort.map do |k| 
        regular_hours_by_week[k]
      end
    end
  end

What I’m doing here is calling tap on a default hash and then populating it via the code within the block. If I was simply iterating over some values, I might use inject or each_with_object, but my needs were a little more complicated here.

This approach adds a little complexity, but in my experience, having to explicitly return a collection at the end of a method can be cumbersome, and I frequently forget about it during refactoring and cause my tests to go red on me.

What do you think? Is Object#tap the new returning? Or should we put this knife carefully back into DHH’s junk drawer for safekeeping? I’m pretty sure Rails didn’t invent this functionality, but that’s where a lot of us might have encountered it first.

Help me decide whether this is elegant or nasty in the comments below.

A Gentle Reminder

I have to warn you, some of my ideas might be bad. I’ll be posting code that I find interesting or stuff that I don’t know exactly how I feel about. If we hit a dud from time to time, it’s only to be expected. But if you want to help me out, consider contributing content to this series. If you have an idea for a guest post, go ahead and email me with the details, and I’ll get back to you.

Looking forward to your thoughts on this one and many more in the coming weeks!

25th Post!

gregory.t.brown@gmail.com (Gregory Brown) — Tue, 07 Jul 2009 05:00:00 -0000

This is the 25th post to RBP blog! Hooray!

We’ve been really happy with how things have gone so far. Conversations have been for the most part civil and lively, we haven’t run out of content, and the blog has seen new content nearly every week.

I know that we aren’t seeing as many voices on a week to week basis as we hoped for, but let’s face it, people are bound to get busy. That having been said, it’d be great to know what readers are thinking about our content so far.

So, what do you think? Ranging from technical issues to ones of personal taste, it’d be nice to know what keeps RBP in your feed reader, and what we can do to keep it there. All feedback is welcome, so go ahead and let us know what’s on your mind.

If you’ve got a great idea for a post, a series, or just some minor nitpick you want to voice, go for it. So far we’ve gained a lot from user responses, so I’d like to keep with that tradition and keep the feedback loop tight.

Now that you’ve seen 25 posts, how should the next 25 look?

Code Blocks: Ruby's Swiss Army Knife

gregory.t.brown@gmail.com (Gregory Brown) — Tue, 07 Jul 2009 04:00:00 -0000

The following blog post is a direct excerpt from the Ruby Best Practices book. If you’ve been enjoying this blog, you’d probably love the book, so I’ve decided to release some content here to give you a sense of what to expect. Enjoy!

UPDATE: For those coming from other languages, Ruby’s code blocks are inherently closures , and provide syntactic sugar for methods that accept Proc objects (Ruby’s anonymous functions). While not strictly necessary for understanding this article, a solid grasp on what closures are and how they work will take you far.

In Ruby, code blocks are everywhere. If you’ve ever used Enumerable, you’ve worked with blocks. But what are they? Are they simply iterators, working to abstract away our need for the for loop? They certainly do a good job of that:

  >> ["Blocks","are","really","neat"].map { |e| e.upcase } 
  => ["BLOCKS", "ARE", "REALLY", "NEAT"]

But other blocks don’t really iterate over collections—they just do helpful things for us. For example, they allow us to write something like:

  File.open("foo.txt","w") { |f| f << "This is sexy" }

instead of forcing us to write this:

  file = File.open("foo.txt","w") 
  file << "This is tedious" 
  file.close

So blocks are useful for iteration, and also useful for injecting some code between pre-processing and post-processing operations in methods. But is that all they’re good for? Sticking with Ruby built-ins, we find that isn’t the case. Blocks can also shift our scope temporarily, giving us easier access to places we want to be:

 "This is a string".instance_eval do 
    "O hai, can has reverse? #{reverse}. kthxbye" 
  end 
  #=> "O hai, can has reverse? gnirts a si sihT. kthxbye"

But blocks aren’t necessarily limited to code that gets run right away and then disappears. They can also form templates for what to do down the line, springing to action when called for:

  >> foo = Hash.new { |h,k| h[k] = [] } 
  => {} 
  >> foo[:bar] 
  => [] 
  >> foo[:bar] << 1 << 2 << 3 
  => [1, 2, 3] 
  >> foo[:baz] 
  => []

So even if we label all methods that accept a block as iterators, we know the story runs deeper than that. With this in mind, we can leverage some basic techniques to utilize any of the approaches shown here, as well as some more advanced tricks. By doing things in a way that is consistent with Ruby itself, we can make life easier for our users. Rather than piling on new concepts, we can allow them to reuse their previous knowledge. Let’s take a look at a few examples of how to do that now.

Working with Enumerable

The most common use of blocks in Ruby might be the most trivial. The following class implements a basic sorted list, and then mixes in the Enumerable module. The block magic happens in each():

  class SortedList 
    include Enumerable 
  
    def initialize 
      @data = [] 
    end 
  
    def <<(element) 
      (@data << element).sort! 
    end 
  
    def each 
      @data.each { |e| yield(e) } 
    end 
  end

Our each() method simply walks over each element in our @data array and passes it through the block provided to the method by calling yield. The resulting iterator works exactly the same as Array#each and Hash#each and all the Ruby built-ins, and indeed simply wraps Array#each in this case:

  >> a = SortedList.new 
  => #<SortedList:0x5f0e74 @data=[]> 
  >> a << 4 
  => [4] 
  >> a << 5 
  => [4, 5] 
  >> a << 1 
  => [1, 4, 5] 
  >> a << 7 
  => [1, 4, 5, 7] 
  >> a << 3 
  => [1, 3, 4, 5, 7] 
  >> x = 0 
  => 0 
  >> a.each { |e| x += e } 
  => [1, 3, 4, 5, 7] 
  >> x 
  => 20

This shouldn’t be surprising. What is really the interesting bit is that by including the module Enumerable, we gain access to most of the other features we’re used to working with when processing Ruby’s built-in collections. Here are just a few examples:

  >> a.map { |e| "Element #{e}" } 
  => ["Element 1", "Element 3", "Element 4", "Element 5", "Element 7"] 
  >> a.inject(0) { |s,e| s + e } 
  => 20 
  >> a.to_a 
  => [1, 3, 4, 5, 7] 
  >> a.select { |e| e > 3 } 
  => [4, 5, 7]

In a lot of cases, the features provided by Enumerable will be more than enough for traversing your data. However, it’s often useful to add additional features that build on top of the the Enumerable methods. We can show this by adding a simple reporting method to SortedList:

  class SortedList 
    def report(head) 
      header = "#{head}\n#{'-'*head.length}" 
      body = map{|e| yield(e)}.join("\n") + "\n" 
      footer = "This report was generated at #{Time.now}\n" 
      [header, body, footer].join("\n") 
    end 
  end

which, when run, produces output like this:

>> puts a.report("So many fish") { |e| "#{e} fish" } 
  So many fish 
  ------------ 
  1 fish 
  3 fish 
  4 fish 
  5 fish 
  7 fish 
  This report was generated at 2008-07-22 22:47:20 -0400

Building custom iterators is really that simple. This provides a great deal of flexibility, given that the code block can execute arbitrary expressions and do manipulations of its own as it walks across the elements. But as mentioned before, blocks can be used for more than just iteration.

Using Blocks to Abstract Pre- and Postprocessing

We looked at the block form of File.open() as an example of how blocks can provide an elegant way to avoid repeating tedious setup and teardown steps. However, files are surely not the only resources that need to be properly managed. Network I/O via sockets is another place where this technique can come in handy.

On the client side, we’d like to be able to create a method that allows us to send a message to a server, return its response, then cleanly close the connection. The first thing that comes to mind is something simple like this:

  require "socket" 

  class Client 

    def initialize(ip="127.0.0.1",port=3333) 
      @ip, @port = ip, port 
    end 

    def send_message(msg) 
      socket = TCPSocket.new(@ip,@port) 
      socket.puts(msg) 
      response = socket.gets 
    ensure 
      socket.close 
    end 
  
  end

This is reasonably straightforward, but what happens when we want to add another method that waits to receive a message back from the server?

  require "socket" 
  
  class Client 
    
    def initialize(ip="127.0.0.1",port=3333) 
      @ip, @port = ip, port 
    end 
    
    def send_message(msg) 
      socket = TCPSocket.new(@ip,@port) 
      socket.puts(msg) 
      response = socket.gets 
    ensure 
      socket.close 
    end 
    
    def receive_message 
      socket = TCPSocket.new(@ip,@port) 
      response = socket.gets 
    ensure 
      socket.close 
    end 
  end

This is starting to look messy, as we have repeated most of the code between send_message and receive_message. Ordinarily, we’d break off the shared code into a private method that the two could share, but the trouble here is that the difference between these two methods is in the middle, not in a single extractable chunk. This is where blocks come to the rescue:

  require "socket" 

  class Client 
    def initialize(ip="127.0.0.1",port=3333) 
      @ip, @port = ip, port 
    end 
  
    def send_message(msg) 
      connection do |socket| 
        socket.puts(msg) 
        socket.gets 
      end 
    end 

    def receive_message 
      connection { |socket| socket.gets } 
    end
     
    private 
    
    def connection 
      socket = TCPSocket.new(@ip,@port) 
      yield(socket) 
    ensure 
      socket.close 
    end 
  
  end

As you can see, the resulting code is a lot cleaner. As long as we use our connection() method with a block, we won’t need to worry about opening and closing the TCPSocket; it’ll handle that for us. This means we’ve captured that logic in one place, and can reuse it however we’d like.

To make things a bit more interesting, let’s take a look at a simple server with which this code can interact, which gives us a chance to look at yet another way that blocks can be useful in interface design.

Blocks as Dynamic Callbacks

There is a lot of power in being able to pass around code blocks just like they were any other object. This allows for the capability of creating and storing dynamic callbacks, which can later be looked up and executed as needed.

In order to play with our Client code from the previous example, we’re going to create a trivial TCPServer that attempts to match incoming messages against patterns to determine how it should respond. Rather than hardcoding behaviors into the server itself or relying on inheritance to handle responses, we will instead allow responses to be defined through ordinary method calls accompanied by a block. Our goal is to get an interface that looks like this:

  server = Server.new 

  server.handle(/hello/i) { "Hello from server at #{Time.now}" } 
  server.handle(/goodbye/i) { "Goodbye from server at #{Time.now}" } 
  server.handle(/name is (\w+)/) { |m| "Nice to meet you #{m[1]}!" } 

  server.run

The first two examples are fairly simple, matching a single word and then responding with a generic message and timestamp. The third example is a bit more interesting, repeating the client’s name back in the response message. This will be accomplished by querying a simple MatchData object, which is yielded to the block.

Though making this work might seem like black magic to the uninitiated, a look at its implementation reveals that it is actually a fairly pedestrian task:

  class Server 
    
    def initialize(port=3333) 
      @server   = TCPServer.new('127.0.0.1',port) 
      @handlers = {} 
    end 
    
    def handle(pattern, &block) 
      @handlers[pattern] = block 
    end 
    
    def run 
      while session = @server.accept 
        msg = session.gets 
        match = nil 
        @handlers.each do |pattern,block| 
          if match = msg.match(pattern) 
            break session.puts(block.call(match)) 
          end 
        end 
        unless match 
          session.puts "Server received unknown message: #{msg}" 
        end 
      end 
    end
     
  end

The handle() method slurps up the provided block using the &block syntax, and stores it in a hash keyed by the given pattern. When Server#run is called, an endless loop is started that waits for and handles client connections. Each time a message is received, the hash of handlers is iterated over. If a pattern is found that matches the message, the associated block is called, providing the match data object so that the callback can respond accordingly.

If you’d like to try this out, use the following code to spin up a server:

  server = Server.new 
  server.handle(/hello/i) { "Hello from server at #{Time.now}" } 
  server.handle(/goodbye/i) { "Goodbye from server at #{Time.now}" } 
  server.handle(/name is (\w+)/) { |m| "Nice to meet you #{m[1]}!" } 
  server.run

Once you have that running and listening for connections, execute the following client code:

  client = Client.new 
  
  ["Hello", "My name is Greg", "Goodbye"].each do |msg| 
    response = client.send_message(msg) 
    puts response 
  end

You will get back something like this:

  Hello from server at Wed Jul 23 16:15:37 -0400 2008 
  Nice to meet you Greg! 
  Goodbye from server at Wed Jul 23 16:15:37 -0400 2008

It would be easy to extend both the client and server to do more interesting things that build on this very simple foundation. Feel free to take a few minutes to play around with that, and then we’ll look at one more block trick that’s fairly common in Ruby.

Blocks for Interface Simplification

Does it feel like the word “server” is written too many times in this code?

  server = Server.new 
  server.handle(/hello/i) { "Hello from server at #{Time.now}" } 
  server.handle(/goodbye/i) { "Goodbye from server at #{Time.now}" } 
  server.handle(/name is (\w+)/) { |m| "Nice to meet you #{m[1]}!" } 
  server.run

When you see code like this, it might be a sign that you could do better. Although there are merits to this somewhat standard approach, we can cheat a little bit with blocks (of course) and make things prettier. It would be nice to be able to write this instead:

  Server.run do 
    handle(/hello/i) { "Hello from server at #{Time.now}" } 
    handle(/goodbye/i) { "Goodbye from server at #{Time.now}" } 
    handle(/name is (\w+)/) { |m| "Nice to meet you #{m[1]}!" } 
  end

As you may recall from an earlier example, it is possible to execute a block within the scope of an instantiated object in Ruby. Using this knowledge, we can implement this handy shortcut interface as a simple class method:

  class Server 
    # other methods same as before 
    def self.run(port=3333,&block) 
      server = Server.new(port) 
      server.instance_eval(&block) 
      server.run 
    end 
  end

This is all you need to get the new interface running, and rounds off our quick exploration of the different ways that you can use blocks to improve your API design while simplifying your method implementations. Let’s recap with a few tips before we wrap up here.

Things to Remember

Keep the following things in mind when using blocks as part of your interface:

If you create a collection class that you need to traverse, build on top of Enumerable rather than reinventing the wheel.

If you have shared code that differs only in the middle, create a helper method that yields a block in between the pre/postprocessing code to avoid duplication of effort.

If you use the &block syntax, you can capture the code block provided to a method inside a variable. You can then store this and use it later, which is very useful for creating dynamic callbacks.

Using a combination of &block and instance_eval, you can execute blocks within the context of arbitrary objects, which opens up a lot of doors for highly customized interfaces.

The return value of yield (and block.call) is the same as the return value of the provided block.

Did you enjoy this post?

If you had fun reading this, definitely consider picking up a copy of Ruby Best Practices . If you need more convincing, there is a whole sample chapter for you to check out in addition to this excerpt. If you’ve already picked up the book and are enjoying it, tell your friends, and consider leaving a review on the Amazon product page . If you don’t have enough time for that, go help me win the popularity contest over at RubyTrends, as there are several books that I admire that still need to be overcome :)

As always, I welcome your thoughts and feedback. Let me know what you think of the techniques shown here, or share your own personal favorite code block trick.

The Decorator Delegator Disco

gregory.t.brown@gmail.com (Gregory Brown) — Sat, 27 Jun 2009 16:00:00 -0000

As promised, we’re back with more design discussion and hopefully some interesting ideas. Let’s start with a quick recap of what has happened so far.

First, Sandi Metz posted on her blog about type specific coupling that a case statement can introduce. Her proposed solution encouraged us to pass the responsibilities down to the individual objects, which is certainly desirable.

Aaron Patterson got in the mix, pointing out the issues that can happen when you are too aggressive about adding methods to core Ruby. When Sandi suggested that Double Dispatch might be a way around this problem, Aaron responded with an implementation using the visitor pattern to accomplish this sort of thing.

I had not seen Aaron’s initial work before setting out to solve the problem on my own, and ended up taking an entirely different path to get there. I’m not much of a patterns guy, but after I had a working implementation, it seems like the approach I took mostly represents a combination of Delegation and Decoration techniques.

A quick demo

I think this code will be easier to understand if I show how it is used right up front. So here’s a tiny slice to get started with:

  module ActionView
    module Helpers 
       class Extensions
          extend Decoration
        
          decorator_for(Array) do
            def as_array
              self
            end
          end
        
          decorator_for(Object) do
            def as_array
              [self]
            end
          end
       end
     
       # totally incomplete, just returns decorated object
       def form_for(record_or_name_or_array, *args, &block)
         Extensions.decorate(record_or_name_or_array)
       end
    end
  end

  include ActionView::Helpers

  p form_for(:foo).as_array #=> [:foo]
  p form_for(Object.new).as_array #=> [#<Object:0x3f47ec>]
  p form_for([1,2,3]).as_array #=> [1,2,3]

In the code above, I’ve implemented Sandi’s as_array helper. I left the actual form_for implementation very incomplete, causing it just to return the decorated object. This is for example purposes only, so you could see that we can indeed call as_array successfully.

Before we check out how this all works, here are two extra hints about what this approach is affording us.

  my_obj = [1,2,3]
  decorated = form_for(my_obj)
  
  p decorated.as_array #=> [1,2,3]
  
  # Raises NoMethodError
  [1,2,3].as_array
  
  # Also raises NoMethodError
  p my_obj.as_array

As you can see, if core extensions are like a meat cleaver, this approach is more like using a scalpel, no changes bleed out into unexpected places. Now that we see how it is used, let’s take a look under the hood of Decorate to see how it is built.

The `Decorate` module

Though fairly densely packed, the whole implementation of Decorate is pretty tiny.

require 'delegate'

# with minor tweaks from tjstankus
module Decoration
  def decorator_for(*types, &block)
    types.each do |type|
      decorators[type] = Module.new(&block)
    end
  end
 
  def decorators
    @decorators ||= {}
  end
 
  def decorate(target)
    obj = SimpleDelegator.new(target)
    
    # walk in reverse order so most specific patches get applied LAST
    target.class.ancestors.reverse.each do |a|
      if decorators[a]
        obj.extend(decorators[a])
      end
    end
    
    return obj
  end
end

Here, we are taking advantage of SimpleDelegator, a class provided from Ruby’s delegate standard library. Here’s a quick glimpse of how it works:

>> require "delegate"
=> true

>> a = [1,2,3]
=> [1, 2, 3]

>> b = SimpleDelegator.new(a)
=> [1, 2, 3]
>> b << 4
=> [1, 2, 3, 4]
>> b.delete_at(1)
=> 2

>> b
=> [1, 3, 4]
>> a
=> [1, 3, 4]

>> b.class
=> SimpleDelegator
>> a.class
=> Array

Essentially, SimpleDelegator provides an easy way to wrap an object within a proxy. This gives us a convenient place to hang per-object behavior without mutating the original object.

  >> def b.kitties
  >>   "MEEEOW"
  >> end
  >> b.kitties
  => "MEEEOW"
  >> a.kitties
  NoMethodError: undefined method `kitties' for [1, 3, 4]:Array
  	from (irb):15

You probably see where this is going now, so let’s get back to Decorate module. If we look at decorator_for, we can get a good sense of how all this magic comes together:

def decorator_for(*types, &block)
  types.each do |type|
    decorators[type] = Module.new(&block)
  end
end

def decorators
  @decorators ||= {}
end

Here, we see that decorator_for basically takes a type or list of types, and a block. The block is then used to define the body of an anonymous module that gets stashed away in a hash for later use. So going back to our example code, we see that the following definitions are actually module definitions. They could have even been written this way:

class Extensions
   extend Decoration
 
   module ArrayDecorator
     def as_array
       self
     end
   end
 
  module ObjectDecorator
     def as_array
       [self]
     end
  end
  
  decorators[Array]  = ArrayDecorator
  decorators[Object] = ObjectDecorator
end

Of course, this lacks the necessary sugar shock, so I show it only to make the implementation clearer. But now that we have a way to stack up modules with per-object behavior in them, and a place to hang that per-object behavior off of, we only need a mechanism to apply it. For this functionality, we turn to the decorate method:

  def decorate(target)
    obj = SimpleDelegator.new(target)
  
    # walk in reverse order so most specific patches get applied LAST
    target.class.ancestors.reverse.each do |a|
      if decorators[a]
        obj.extend(decorators[a])
      end
    end
  
    return obj
  end

We want to be able to preserve the ability to use super in our decorated method calls, and we definitely wanted to pick up extensions to objects higher in the inheritance chain without any duplication. So this meant we needed to do something a little more complicated than key the target object’s type directly to a decorator module.

Rather than just picking the most recent ancestor, this code walks the chain in reverse order so that the modules can neatly stack on top of one another. In short, this means that the decorator for Object gets applied before the one for Array so that you can emulate an inheritance relationship in your extensions.

This pretty much sums up the whole implementation, so let’s just take a look at one more example before evaluating the pros and cons of this approach.

An alternative to core extensions

Here is a bit of code that completely covers the core extensions that Sandi needed for her Rails patch, without the core extensions:

   
  class Extensions

     extend Decoration
     
     decorator_for Symbol, String do
       def form_object_name
         self
       end

       def as_fields_for_form_object(args)
         args.first
       end

       def acts_like_model?
         false
       end
     end

     decorator_for Array do
       def as_form_object
         last
       end

       def as_array
         self
       end
     end

     decorator_for Object do
       def as_form_object
         self
       end

       def as_fields_for_form_object(args)
         as_form_object
       end

       def form_object_name
         ActionController::RecordIdentifier.singular_class_name(self)
       end

       def as_array
         [self]
       end

       def acts_like_model?
         true
       end
     end
     
  end

You would use the same approach I suggested before to wire this up, something like Extensions.decorate(my_obj)

Pros for this solution

There are definitely things about this technique that I like. The obvious benefit is that it prevents core hackery, and even goes a step beyond something like my_object.extend(SomethingSpecial), since it only extends behavior into a throwaway proxy object.

Another clear benefit is that defining extensions is about as easy as it is to do raw core extensions. Because the blocks are used as module definitions, you can do pretty much anything you’d ordinarily do when defining methods. This lowers the amount of ‘special stuff’ you need to remember.

Perhaps the most interesting thing however, is that this approach can be used to apply customized behavior to several types of objects at once, and can also be used to apply behaviors based on what mixins are included in an object. This means there is nothing stopping you from doing something like decorator_for(Enumerable) or decorator_for(Comparable), which provides you a little extra flexibility beyond the traditional inheritance hierarchy.

Another interesting aspect of this is that decorators can be implemented at a per-module (or per-class) level, which means that different libraries can have different extensions without interfering with each other.

Keep in mind, it’s not all roses. Let’s take a look at some of the pitfalls.

Cons for this solution

A major drawback here is that we’re still relying on types. Whether its a class or module, we still expect an object to be a certain thing, which sort of goes against traditional duck typing in which we’d rather make assumptions based on what an object can do rather than what it is. So it might be nicer to apply these decorators based on what the target object responds to, not what ancestors it has.

There is also the performance overhead factor. I have not benchmarked yet, but I suspect that the cost of both building up a SimpleDelegator and doing proxy calls is non-negligible. While this may not be an issue in many cases, for code that needs to run in tight loop or be scaled heavily, this approach may be too heavy for its benefits to outweigh its costs. But of course, this is a huge YMMV situation, and without hard numbers it’s tough to say to what extent this would be a huge issue.

Perhaps the most fatal flaw with the current setup is that respond_to? gets delegated to the target object, so with the current implementation, unless you define respond_to? yourself, it will not pick up any of your new methods. I imagine that this is something that can be fixed, I just have not looked into it yet.

Finally, there is the legitimacy problem. As Sandi said in the comments on Aaron’s article, sometimes a case statement is just a case statement. If we go around filling all our code with high-architecture bazookas when all that was needed was a pen-knife, there are bound to be consequences. Is this overkill or awesome? I don’t really know, and I imagine it depends on the situation.

Conclusions

When Aaron and I compared our solutions to Sandi’s problem, we basically concluded that both of our approaches might be useful for different things. Aaron’s shines when dealing with providing type-specific implementations of a particular behavior, which is mostly just the visitor pattern shining through. My approach is probably better for situations in which you need to collect several behaviors in one place.

Ultimately, this may be a matter of preference, depending on whether you want to abstract things based on the method level or the object level. Of course, sometimes neither is necessary, and that may be an important fact to remember.

I am very much interested in what readers have to say. Please check out Sandi’s article , then Aaron’s , then let me know here which approaches you might take along with their context. If you have your own ideas that are totally different than ours, I want to know about that too.

We need more conversations like these in our community, so let’s start here and see where it takes us.

Quack Attack: Making Your Code More Rubyish

gregory.t.brown@gmail.com (Gregory Brown) — Tue, 09 Jun 2009 13:00:00 -0000

I’ve been doing some FFI work recently, which means that I’ve needed to wrap underlying C libraries so that I can call them from Ruby. While I won’t get into how the low level wrappers work, I can show you what the raw API calls look like for just a few functions:

  trip = API.PCMSNewTrip(server_id)
  API.PCMSNumStops(trip)
  API.PCMSAddStop(trip, string)
  API.PCMSGetStop(trip, index, string_ptr, buffer_size)
  API.PCMSDeleteStop(trip, index)
  API.PCMSClearStop(trip)

All things considered, this looks pretty good for a direct wrapper on top of a C library. In fact, it’s relatively simple to mirror this to a more normalized Ruby layout. We can start by noticing that these calls are basically object oriented, focusing on the Trip object. While a Trip has other responsibilities, among them is managing a list of stops. With this in mind, we can flesh out a basic Trip object:

class Trip
  def initialize(server_id)
    @server_id = server_id
    @pointer = API.PCMSNewTrip(@server_id)
    @stops = StopList.new(self)
  end
  
  attr_reader :stops
  
  def call(*args)
    API.send("PCMS#{args.first}",  @pointer, *args[1..-1])
  end
end

The Trip#call helper removes some of the duplication for us, but it’ll be easier to see how it works in just a moment. For now, it’s worth pondering what a StopList should be.

If you look at the functions listed for dealing with stops, you’ll notice they map nicely to one of Ruby’s structures. We’re dealing with an ordered list of objects that can be added to and removed from. It can also be queried for its length, and deleted entirely. These features sure sound a lot like Ruby’s Array object, don’t they?

With this in mind, let’s do a quick experiment in interface design:

class StopList

  include Enumerable

  def initialize(trip)
    @trip = trip
  end

  def length
    @trip.call :NumStops
  end

  def <<(loc)
    @trip.call :AddStop, loc
  end

  def [](index)
    ptr = FFI::MemoryPointer.new(:char, 100)
    @trip.call :GetStop, index, ptr, 101
    ptr.read_string
  end

  def delete_at(index)
    @trip.call :DeleteStop, index
  end

  def each
    length.times do |i|
      yield self[i]
    end
  end

  def clear
    @trip.call :ClearStops
  end

end

Without paying too much attention to the implementation details, let’s take a look at what behaviors this new object supports:

  t = Trip.new(server_id)
  
  t.stops << "New Haven, CT"
  t.stops << "Naugatuck, CT"
  t.stops << "Boston, MA"
  
  p t.stops.length #=> 3
  
  p t.stops[2] #=> "02205 Boston, MA, Suffolk"
  
  t.stops.delete_at(1)
  p t.stops[1] #=> "02205 Boston, MA, Suffolk"
  
  p t.stops.map { |e| e.upcase } #=> [ "06511 NEW HAVEN, CT, NEW HAVEN",
                                 #     "02205 BOSTON, MA, SUFFOLK" ]
  
  t.stops.clear
  p t.stops.length #=> 0

If this sort of interaction looks familiar to you, it’s because you’ve likely already done things like this thousands of times. But to make it blindingly obvious, let’s replace Trip#stops with an Array.

stops = []

stops << "New Haven, CT"
stops << "Naugatuck, CT"
stops << "Boston, MA"

p stops.length #=> 3

p stops[2] #=> "Boston, MA"

stops.delete_at(1)
p stops[1] #=> "Boston, MA"

p stops.map { |e| e.upcase } #=> ["NEW HAVEN, CT", "BOSTON, MA"]

stops.clear
p stops.length #=> 0

You’ll notice that aside from lacking the location name normalization that our real code does implicitly, the key points we’ve highlighted have exactly the same behavior, using exactly the same interface. One benefit is immediately obvious after seeing this; the API for StopList doesn’t require you to learn anything new.

A more subtle gain that comes with this approach is that so long as it is restricted to the subset which StopList supports, code which expects an Array-like thing does not need to change, either.

For example, the following code will work just fine with either an Array or a StopList:

def humanized(list)
  list.each_with_index do |e,i|
    puts "#{e} (#{i+1} / #{list.length})"
  end
end

This makes things easier to test, and easier to be re-used for different purposes. Both are solid reasons for using this technique.

Of course, I’ve been glossing over a semi-major issue in the original code here, which I am sure has frustrated our more pedantic readers. The current StopList code, while quite useful, does not quack perfectly with Array. We needn’t look far for signs of divergence.

p t.stops << "Chicago, IL" #=> 1
p t.stops.delete_at(2)     #=> 1
p t.stops.clear            #=> nil

These side-effect bearing functions are returning their C based values, which are different than what you’d expect from a Ruby Array. Luckily, each of these are easy to remedy.

In the case of the append operator (<<), we should return the StopList itself, to permit chaining:

def <<(loc)
  @trip.call :AddStop, loc
  return self
end

To play nice with Array, our delete_at method should return the deleted object:

  def delete_at(index)
    obj = self[index]
    @trip.call :DeleteStop, index
    return obj
  end

Finally, since clear may also be chained, it should return the original object as well.

def clear
  @trip.call :ClearStops
  return self
end

With these fixes in place, we can re-visit our previous example:

p t.stops << "Chicago, IL" #=> #<Trip::StopList:0x0fcac ...>
p t.stops.delete_at(2)     #=> "60607 Chicago, IL, Cook"
p t.stops.clear            #=> #<Trip::StopList:0x0fcac ...>

There are probably some other minor details to catch, but now that our Array-ish StopList is “Good Enough For Government Work”, we have a nice stopping point. Let’s wrap things up with a little summary of things to remember.

Guidelines For Making Your Code More “Rubyish”

This is just one technique among many for improving your code, but I’d argue its a fairly important one. If you have a structure that mimics a subset of a core Ruby object’s capabilities, you can gain a lot by standardizing on a compatible interface. While sometimes the similarities end at the Enumerable and Comparable mixins, it’s reasonable to stretch things farther when it makes sense to do so. If you go that route (as we did here), there are just a few things to keep in mind:

You don’t need to implement every last feature of a core Ruby object in order to use this technique. So many functions rely on just a handful of available methods, that it makes sense to use this technique even when your problem domain is very small.

For the features you do implement, take care to maintain the same interface both on input and output. It’s fine to not support certain use cases, or to add extensions for new ones, but you should not diverge in the behaviors you do implement unless you have a good reason to.

Pay close attention to the return values of side-effect inducing functions, especially the ones mentioned in this article. Many Ruby methods are designed to be chainable, and breaking that feature can create a mess.

While this technique opens the door for using primitive objects for testing higher level functions, do not forget to adequately test the functionality of the actual objects you are implementing. Basically, make sure your code really quacks like a duck before substituting it with a duck somewhere else.

To our readers: Where have you seen good uses of this technique in action? Have you tried it yourself and run into any problems? Please give your answers to these questions, as well as any other discussion points in the comments.

RubySpec as a Community Resource (Interview w. Brian Ford)

gregory.t.brown@gmail.com (Gregory Brown) — Thu, 04 Jun 2009 07:52:00 -0000

Though I still need to collect the details, I’m about to start on another major open source project, called Unity . It will be a community driven effort to provide a nice web resource that builds on top of the RubySpec project with reporting and search capabilities.

But readers might wonder what RubySpec has to do with them, if they are not language implementers. Here’s what Brian Ford had to say.

In an ideal world, what would the RubySpec project do for the Ruby community?

1. Provide a reasonably precise definition of the Ruby programming language so that there can be a certain degree of uniformity among the implementations. The goal is for the Ruby user to not have to think about which implementation her code runs on until she needs to, rather than writing code that works on one implementation and porting it if necessary. All software has a life cycle and the needs of the software are not always constant. A Ruby programmer should be able to develop using MRI on their laptop and deploy on Rubinius or JRuby without missing a beat, for example. Note that I use “Ruby user” and “Ruby programmer” with a distinction. A Ruby user might be anyone who relies on or provides software written in Ruby, not just someone who writes software in Ruby. So I envision a uniform definition of Ruby benefiting every strata of the Ruby community.

2. Provide quality assurance and regression notification for MRI and all implementations. People put a huge amount of trust in an implementation when they decide to invest large amounts of money in developing a software product. We’d like them to get some assurance for the trust they put in. Programmers are human and make mistakes. Automating the detection of mistakes is a no-brainer.

3. Improving the quality of Ruby as a language by discovering dusty corners and inconsistencies. Recently, a number of inconsistencies in bang methods (e.g. String#lstrip!) were discovered by one of the RubySpec contributors. Matz quickly fixed up the issues. (You can read the gory details here: http://redmine.ruby-lang.org/issues/show/1550). Ruby as a programming language certainly exists in Matz’s brain. But Ruby as an implementation (MRI) exists in many developers’ brains. RubySpec is an attempt to expose all that knowledge and those assumptions in an objective manner.

4. Experimentation with implementations and the Ruby language itself. I have recently implemented nearly a dozen variations of Hash for Rubinius to determine which algorithms perform best. In each case, I start by writing code that will pass the RubySpec Hash specs. The specs have been generalized to use a helper method rather than referencing the Hash class constant directly. This has been a huge benefit, especially in Rubinius where the core library Hash class is written entirely in Ruby. I can inherit from Hash and override any methods to write a completely new implementation that does not interfere with the existing Hash class. The RubySpecs also provide a huge safety net and testing ground for trying out new language features and seeing how they interact with existing features.

5. A learning tool that provides Ruby programmers with concrete examples of code that demonstrates every single Ruby language feature. The Pickaxe book may have better prose, but when it comes to comprehensiveness, I want RubySpec to be number one. And while we have a lot of work to do to make the spec description strings better, you can already learn a lot about Ruby by reading the specdoc output.

With everything changing so fast, I imagine keeping the specs up to date is a constant struggle. How do implementers keep up with what’s going on?

Some things are changing fast but when you look at how many distinct behaviors RubySpec covers, a lot isn’t changing. It’s hard keeping up with the 1.9 changes. So far in Rubinius, we haven’t targeted 1.9 specifically, but we have a contributor, Marc-Andre Lafortune, who has added a ton of 1.8.7 and 1.9 features to the core libraries. As with anything, you do it one thing at a time. Having RubySpec available to tell you if you are doing it right is a big help.

I would really love to make RubySpec a household name in the general Ruby community. The project I’m breaking ground on now (called Unity), will hopefully help do this. What sort of information do you think is most valuable to pull out from RubySpec, and who do you see benefiting from it?

Again, the primary goal of RubySpec is to provide a definition of the Ruby programming language along with a way to test that an implementation conforms to the definition. So primary pieces of information are which specs pass and which fail on a given implementation. Evan and I have discussed adding a scoring mechanism to MSpec that provides a single percentage number as a measure of an implementation’s conformance to the standard set by RubySpec. This is something that can give users better information about an implementation’s completeness when it goes bandying about benchmarking numbers. I’ll be implementing this in MSpec shortly.

RubySpec spans a ton of functionality. It’s amazing to see how much work has already been done. However, there must be some dark spots still left. What areas of Ruby are still not adequately specified?

That is the 10 million dollar question. We can infer something about completeness based on implementations like JRuby that run applications the same as MRI and pass the vast majority of the RubySpec cases. When implementations discover bugs in their own code and enhance the RubySpec coverage, we get a nice closed feedback loop.

A lot of the standard library still needs to be covered. There are also some little used methods in the core library that lack specs. The procedural-style methods in Kernel come to mind (e.g. using methods without receivers like #gets, #puts, #sub, etc. that operate on $_). We have a utility that creates the spec files for methods and leaves marker specs that we tag as incomplete. In Rubinius, for example, you can run ‘bin/mspec tag —list incomplete’ and get a printout of specs that need to be reviewed for completeness.

Ultimately, we need a uniform methodology for auditing the completeness and accuracy of the specs. This is still a work in progress.

Charles Oliver Nutter (of JRuby) chimes in with some additional feedback on this question:

I would inject another small answer here:

In my experience with RubySpec, the areas least covered are unfortunately often the areas least understood and therefore those most in need of coverage. For example, OpenSSL specs are practically nonexistent, and yet it’s such a crucial bit of functionality for any app doing SSL (as a client or a server) or working with any PKI or certificate stuff. But it’s also very hard to test…most people have zero knowledge of crypto, and so finding people that can write those specs is about as easy as finding people that can write OpenSSL wrappers for new implementations. So there’s definitely specific areas of RubySpec that need someone with domain knowledge to dive in.

As you can see, RubySpec is a vibrant, exciting project with a lot of challenges it needs to face. My plans are to do my part by building up the Unity app to make this awesome body of work more accessible to the Ruby community at large. But definitely don’t wait on it before getting involved, check out RubySpec today and see if there is a way you can pitch in, especially if you think you can help with some of the projects mentioned here.

To our readers: What sorts of things can you see RubySpec being used for? What kind of data are you interested in seeing reports on? Do you think Brian’s goals for RubySpec are attainable? Share your thoughts in the comments below.

Reading Ruby's Standard Library for Fun and Profit

gregory.t.brown@gmail.com (Gregory Brown) — Sun, 24 May 2009 18:25:00 -0000

Note: This post is inspired by JEG2’s excellent code reading talk at MWRC 2009, called LittleBIGRuby Go watch it if you have time, then come back and read this. You might also want to check out the Question 5 Ways interview at Pat Eyler’s “On Ruby” blog for more code reading goodness.

We all need to hunt bugs and we all need to integrate our code with other systems. Some of us need to make use of undocumented libraries, and others need to examine code to perform security audits. Why is it then, that so many developers suck at reading code?

Almost a decade ago, Joel Spolsky would have told you it’s harder to read code than it is to write it , and that was probably true at one point. But times have changed, and in a language like Ruby, this definitely does not have to be the case. As an avid code reader, I’ll let you in on a secret: All you need to do is practice!

Beginners and even intermediate developers may need a lot of hand holding at first, that’s only to be expected. However, if you want to progress to higher levels of understanding, you must turn to the source. The merits of higher level idioms and design strategies won’t be very clear until you need to understand someone else’s code. Once you start digging around in someone else’s code base, you’ll learn a lot about your own strengths and weaknesses.

But where should you start? It’s tempting to suggest that you should just follow your favorite projects on Github and keep an eye on the patches as they fly. However, this can be a bit overwhelming at first, and it may be hard to keep up with the velocity and transient nature of active open source projects. For this reason, I suggest picking a slower moving target that is still useful to you. Ruby’s Standard Library fits this description perfectly.

How I Read Code

I’m going to walk through the process I generally follow when I’m reading code for the purpose of understanding its implementation. I sometimes change things up when I have a particular goal in mind, but most of what I’m about to cover is generally applicable to digging into any new code base. Keep in mind though, our goal here is mainly just to explore a bit and maybe learn a thing or to along the way.

I’ve chosen the Observable library here because it is small, self-contained, and easy to understand. There are many libraries like this in the stdlib, so if you feel motivated after reading this post, you might want to go searching for a few other low hanging fruit to test your skills on.

I’ve done what I can to boil the process down to a few repeatable steps, so you’re welcome to follow along at home if you’d like.

Start with a simple example.

I don’t like diving into code without at least a little bit of context. So this means that before I go source diving, I’ll typically use the API documentation (if it exists), to code up a simple example. If I can’t find documentation, I’ll search the web for examples. It’s relatively rare to come up completely empty, and a bit of a warning sign if you do. But since Observable is well documented , it’s easy enough to come up with something.

We’re dealing with the Observer design pattern (also known as Pub-Sub), and the first idea that came to mind here for me was a simple chat model. Users could subscribe to a room and the room would publish the messages that were processed to them. I wanted the transcripts to be personalized, so that they looked something like this:

  = Greg's Transcript =
  Me: Hi
  Jia: Hello
  Me: Fun, huh?
  Jia: Yeah!

  = Jia's Transcript =
  Gregory: Hi
  Me: Hello
  Gregory: Fun, huh?
  Me: Yeah!

Thinking from the outside in, we can imagine the Ruby code used to generate this output:

  room = Room.new

  greg   = Person.new("Gregory", room)
  jia    = Person.new("Jia", room)

  greg.says "Hi"
  jia.says "Hello"

  greg.says "Fun, huh?"
  jia.says "Yeah!"

  puts "= Greg's Transcript ="
  puts greg.transcript + "\n"

  puts "= Jia's Transcript ="
  puts jia.transcript

Ultimately, what the Observable module buys us is the ability to track subscribers implicitly rather than explicitly. While it’d be pretty easy to roll your own code here, you can see in the following definition that Observable provides a few shortcuts for us:

  require "observer"

  class Room 
    include Observable

    def receive(message, sender)
      changed
      notify_observers(message, sender)
    end
  end

  class Person
    def initialize(name, room)
      @name, @room = name, room
      @transcript  = ""
      @room.add_observer(self)
    end

    attr_reader :transcript, :name

    def update(message, sender)
      if sender == self
        message = "Me: #{message}\n"
      else
        message = "#{sender.name}: #{message}\n"
      end
    
      @transcript << message
    end

    def says(message)
      @room.receive(message, self)
    end
  end

This is all the code you need to reproduce the desired output, so if you’re
interested in tinkering with it a bit, go ahead and do that now. The real purpose of doing this however was not to implement something useful. Instead, it was to identify some entry points into Observable that can be our first areas of focus.

If you look over the code carefully, you find that changed, notify_observers, and add_observer are the keys to what makes our code tick (And incidentally, the only parts that we didn’t implement ourselves.) Let’s dig a little deeper with those targets in mind.

Hunt for tests, if they exist.

Many of Ruby’s standard libraries have tests distributed with the source, some do not. Unfortunately in the case of Observable, I couldn’t find any tests for it in the Ruby source distribution. However, that didn’t mean that it was time to give up. In cases where MRI/YARV do not have tests, you can try to turn to the great RubySpec project, which is attempting to codify the behavior of Ruby with executable RSpec-like tests.

As it turns out, RubySpec has “several tests”: for Observable. They are split up by each individual function. As an example, here are the specs for notify_observers:

  describe "Observer#notify_observers" do
 
    before(:each) do
      @observable = ObservableSpecs.new
      @observer = ObserverCallbackSpecs.new
      @observable.add_observer(@observer)
    end
 
    it "must call changed before notifying observers" do
      @observer.value.should == nil
      @observable.notify_observers("test")
      @observer.value.should == nil
    end
 
    it "verifies observer responds to update" do
      lambda {
        @observable.add_observer(@observable)
      }.should raise_error(NoMethodError)
    end
 
    it "receives the callback" do
      @observer.value.should == nil
      @observable.changed
      @observable.notify_observers("test")
      @observer.value.should == "test"
    end
 
  end

This code uses some helper objects, which are defined as follows:

  require 'observer'
 
  class ObserverCallbackSpecs
    attr_reader :value
 
    def initialize
      @value = nil
    end
 
    def update(value)
      @value = value
    end
  end
 
  class ObservableSpecs
    include Observable
  end

You can see how the structure of these mirror our earlier example. When you combined them with the specs, you learn quite a bit about this method.

First of all, notify_observers doesn’t do anything if you don’t first call the changed method:

  it "must call changed before notifying observers" do
    @observer.value.should == nil
    @observable.notify_observers("test")
    @observer.value.should == nil
  end

Also, we see that any of the observers used need to implement the update callback, matching the signature of notify_observers:

  it "verifies observer responds to update" do
    lambda {
      @observable.add_observer(@observable)
    }.should raise_error(NoMethodError)
  end

Of course, when the callback exists and the observable object has been marked as changed, we see a successful result:

  it "receives the callback" do
    @observer.value.should == nil
    @observable.changed
    @observable.notify_observers("test")
    @observer.value.should == "test"
  end

While these specs aren’t necessarily giving us every last detail, they provide a general outline of what to expect when we look directly at the source. This will help us avoid getting overwhelmed when working through the actual implementation. I’ll leave it to you to check out the rest of the Observable specs if you’d like. Doing so may help you understand the code in the following section.

Dig into the source with kindness and curiosity

The main purpose of reading over the tests first is that they give you a bit of insight into what behaviors the implementation code needs to satisfy. Assuming you didn’t skip the last section, it should be pretty clear what’s going on in the following method definition:

  def notify_observers(*arg)
    if defined? @observer_state and @observer_state
      if defined? @observer_peers
        @observer_peers.each { |k, v| k.send v, *arg }
      end
      @observer_state = false
    end
  end

Of course, the ‘why’ is as important as the ‘how’ when you’re exploring someone else’s code. Without looking any farther, one thing that tripped me up was this line:

  if defined? @observer_state and @observer_state

It was immediately clear to me what it did, but not why it was needed. Upon further investigation, I remembered one of my bad habits. The following code will issue a warning as written:

  module A
    def foo
      @foo
    end
  end

  class B
    include A
  end

  B.new.foo

However, we can avoid this warning using the exact same approach used in Observable, simply by checking whether the instance variable is defined before accessing it:

  module A
    def foo
      @foo if defined?(@foo)
    end
  end

Yes, this is more verbose, and seems a bit redundant. But writing code this way does have a real benefit. If you follow this convention of checking whether an instance variable is defined whenever you aren’t sure it will be, this warning can be used to easily catch typos. The following example, when run with warnings enabled, will illustrate how:

  class A
    def foo
      @foo = 10
      bar
    end

    def bar
      @bar = @fooo
    end
  end

  A.new.foo

At this point, I already found a helpful reminder by walking through this code. While the rest of the source was an interesting read, this was my takeaway. Please go ahead and read the full source and let me know in the comments if you found anything of interest.

In fact, I have a question for our readers. Can you find any reason why the following code is written as it is?

  # Query the changed state of this object.
  #
  def changed?
    if defined? @observer_state and @observer_state
      true
    else
      false
    end
  end

This looks a bit like a wart to me, and if anything, seems like a long way to go in order to avoid !!obj. But maybe someone else sees it in a different light? Actually, that reminds me…

Caveats about the Standard Library

While Ruby’s stdlib is a great place to learn new things, not everything in it is downright beautiful. Some things are older than others, some reflecting the rust that comes when code is not updated to reflect the latest techniques.

Furthermore, standard library code tends to be less clever than the sort of stuff we might write for our scripts and gems, by design. You’ll find that in many places, explicit and simple code is favored over tricky stuff. I imagine this is for maintainability purposes.

Like anything else, you’ll need to do a bit of hunting to find the right code to learn from. This practice in and of itself will prove to be useful, so don’t be afraid if you run across some cruft now and again.

Of course, another good thing about reading code is that it often inspires us to write code. While looking through the standard library, consider putting together documentation patches, adding tests, and fixing things you don’t like. I’m sure the folks on ruby-core would be happy to look at your contributions, and it’s another great way to learn.

Key Things To Remember

Code reading is just as important as code writing. The standard library has about 100 places for you to look for inspiration, and its more likely than not that you’ll find something of interest if you pick one at random. If you repeat this process, you’ll get a better understanding of how Ruby itself works, and be able to carry this experience into your own work.

Start by playing with some examples, then look for tests, either in the source or in the RubySpec project. Once you feel like you understand how to use a feature, investigate how it works, and then ask yourself why it is written the way it is. Don’t expect to understand the whole thing all at once, and don’t worry if it takes some time to adjust to someone else’s style.

If you do this often enough, you’ll gain a valuable skill that’ll pay off like crazy, especially if you work on open source software. You’ll notice both patterns and anti-patterns, and this will influence the code you write. In the end, your fellow code readers will thank you :)

Hello World (Literally)

gregory.t.brown@gmail.com (Gregory Brown) — Tue, 05 May 2009 06:42:00 -0000

If Google Analytics is right, we’ve reached 68 countries in the last three days. Although I guess this doesn’t mean much at all on the internet, I think it still makes for a pretty map:

From RBP

Of course, I’d like to back up these statistics with some direct data, so I’ve got three questions for our readers:

Where are you from?
What is the Ruby scene like where you live?
What would you like to see on the RBP blog?

Please join in the conversation and let us know who you are. So far, the discussions on this blog have been great and I want to get to know more of our readers. We’ll resume regularly scheduled deep tech content soon, but hopefully this small diversion will prove to be interesting.

Fun with Class.new

gregory.t.brown@gmail.com (Gregory Brown) — Thu, 30 Apr 2009 17:55:00 +0000

Update: I came across an inlink to this page that was layering in advertisements in a frame. Luckily, there are technical solutions to at least some social problems, and you may now browse again in peace :)

If you’ve worked with Ruby for at least a little while, you might already know that classes in Ruby are objects themselves, in particular, instances of Class. Before I get into the fun stuff, let’s quickly recap what that means.

Here’s the ordinary way we define classes, as you all have seen.

  class Point
    def initialize(x,y)
      @x, @y = x,y
    end
    
    attr_reader :x, :y
    
    def distance(point)
      Math.hypot(point.x - x, point.y - y)
    end
  end

The interesting thing is that the previous definition is essentially functionally equivalent to the following:

  Point = Class.new do
    def initialize(x,y)
      @x, @y = x,y
    end
  
    attr_reader :x, :y
  
    def distance(point)
      Math.hypot(point.x - x, point.y - y)
    end
  end

This always struck me as a beautiful design decision in Ruby, because it reflects the inherent simplicity of the object model while exposing useful low level hooks for us to use. Building on this neat concept of anonymously defined classes, I’ll share a few tricks that have been useful to me in real projects.

Cleaner Exception Definitions

This sort of code has always bugged me:

  module Prawn
    module Errors
     
       class FailedObjectConversion < StandardError; end
     
       class InvalidPageLayout < StandardError; end        
     
       class NotOnPage < StandardError; end

       class UnknownFont < StandardError; end   

       class IncompatibleStringEncoding < StandardError; end     

       class UnknownOption < StandardError; end

    end
  end

Although there are valid reasons for subclassing a StandardError, typically the only reason I am doing it is to get a named exception to rescue. I don’t plan to ever add any functionality to its subclass beyond a named constant. However, if we notice that Class.new can be used to create subclasses, you can write something that more clearly reflects this intention:

  module Prawn
    module Errors
       FailedObjectConversion = Class.new(StandardError)
            
       InvalidPageLayout = Class.new(StandardError)     
     
       NotOnPage = Class.new(StandardError)

       UnknownFont = Class.new(StandardError)

       IncompatibleStringEncoding = Class.new(StandardError)     

       UnknownOption = Class.new(StandardError) 

    end
  end

This feels a bit nicer to me, because although it’s somewhat clear that these are still subclasses, I don’t have an ugly empty class definition that will never be filled. Of course, we could make this more DRY if we mix in a little const_set hackery:

module Prawn
  module Errors
  
    exceptions = %w[ FailedObjectConversion InvalidPageLayout NotOnPage
                    UnknownFont IncompatibleStringEncoding UnknownOption ]

    exceptions.each { |e| const_set(e, Class.new(StandardError)) }

  end
end

Even with this concise definition, you’ll still get the functionality you’d expect:

>> Prawn::Errors::IncompatibleStringEncoding.ancestors
=> [Prawn::Errors::IncompatibleStringEncoding, StandardError, Exception, Object, Kernel]
>> raise Prawn::Errors::IncompatibleStringEncoding, "Bad string encoding"
Prawn::Errors::IncompatibleStringEncoding: Bad string encoding
	from (irb):33
	from :0

You can even take it farther than this, dynamically building up error classes by a naming convention. If that sounds interesting to you and you don’t mind the fuzziness of a const_missing hook, you’ll want to check out James Gray’s blog post “Summoning Error Classes As Needed”. Though I tend to be a bit more conservative, there are definitely certain places where a hack like this can come in handy.

The drawback of using any of these methods discussed here is that they don’t really play well with RDoc. However, there are easy ways to work around this, and James details some of them in his post. In general, it’s a small price to pay for greater clarity and less work in your code.

Continuing on the theme of dynamically building up subclasses, we can move on to the next trick.

Safer Class Level Unit Testing

In my experience, it’s a little bit tricky to test code that maintains state at the class level. I’ve tried everything from mocking out calls, to creating a bunch of explicit subclasses, and even have done something like klass = SomeClass.dup in my unit tests. While all of these solutions may do the trick depending on the context, there is a simple and elegant way that involves (you guessed it) Class.new.

Here’s a quick example from a patch I submitted to the builder library that verifies a fix I made to the BlankSlate class:

  def test_reveal_should_not_bind_to_an_instance
    with_object_id = Class.new(BlankSlate) do
      reveal(:object_id)
    end

    obj1 = with_object_id.new
    obj2 = with_object_id.new

    assert obj1.object_id != obj2.object_id,
       "Revealed methods should not be bound to a particular instance"
  end

Notice here that although we are doing class level logic, this test is still atomic and does not leave a mess behind in its wake. We get to use the real reveal() method, which means we don’t need to think up the mocking interface. Because we only store this anonymous subclass in a local variable, we know that our other tests won’t be adversely affected by it, it’ll just disappear when the code falls out of scope. The code is clear and expressive, which is a key factor in tests.

If you’re looking for more examples like this, you’ll want to look over the rest of the BlankSlate test case . I just followed Jim Weirich’s lead here, so you’ll see a few other examples that use a similar trick.

For those interested, the thing that sparked my interest in writing this article today was a tiny bit of domain specific code I had cooked up for my day to day work, which needed to implement a nice interface for filtering search queries at the class level before they were executed.

  class FreightOffer::Rail < FreightOffer
    hard_constraint do |query|
      query[:delivery] - query[:pickup] > 5.days
    end

    soft_constraint do |query|
      query[:asking_price] < 5000.to_money
    end
  end

While it’s easy to test these constraints once they’re set up for a particular model, I wanted to be able to test drive the constraint interface itself at the abstract level. The best way I could come up with was to write tests that used Class.new to generate subclasses of FreightOffer to test against, which worked well. While I won’t post those tests here, it’s a good exercise if you want to get the feel for this technique.

The next trick is a little bit different than the first two, but can really come in handy when you want to inject a little syntactic diabetes into the mix.

Parameterized Subclassing

You might recognize the following example, since it is part of the sample chapter of Ruby Best Practices . More than just a shameless plug though, I think this particular example shows off an interesting technique for dynamically building up subclasses in a low level system.

Let’s start with some vanilla code and see how we can clean it up, then we’ll finally take a look under the hood. What follows is a Fatty::Formatter, which abstracts the task of producing output in a number of different formats.

  class MyReport < Fatty::Formatter 
  
    module Helpers 
      def full_name 
        "#{params[:first_name]} #{params[:last_name]}" 
      end 
    end 
    
    class Txt < Fatty::Format 
      include MyReport::Helpers 
       def render 
        "Hello #{full_name} from plain text" 
       end 
    end 
    
    # use a custom Fatty::Format subclass for extra features 
    class PDF < Prawn::FattyFormat 
      include MyReport::Helpers 
      def render 
        doc.text "Hello #{full_name} from PDF" 
        doc.render 
      end 
    end 
    
    formats.update(:txt => Txt, :pdf => PDF) 
  end

The MyReport class in the previous code sample is little more than a glorified “Hello World” example that outputs text and PDF. It is pretty easy to follow and doesn’t really do anything fancy. However, we can certainly clean it up and make it look better:

  class MyReport < Fatty::Formatter 
    
    helpers do 
      def full_name 
        "#{params[:first_name]} #{params[:last_name]}" 
      end 
    end 
    
    format :txt do 
      def render 
        "Hello #{full_name} from plain text" 
      end 
    end 
    
    format :pdf, :base => Prawn::FattyFormat do 
      def render 
        doc.text "Hello #{full_name} from PDF" 
        doc.render 
      end 
    end 
    
  end

I think you’ll agree that this second sample induces the kind of familiar sugar shock that Ruby coders know and love. It accomplishes the same goals and actually wraps the lower level code rather than replacing it. But is there some sort of dark magic behind this? Let’s peek behind the curtain:

  def format(name, options={}, &block) 
    formats[name] = Class.new(options[:base] || Fatty::Format, &block) 
  end

As you can see, it is nothing more than a hash of formats maintained at the class level, combined with a call to Class.new to generate the subclass. No smoke and mirrors, just the same old Ruby tricks we’ve been using throughout this article. The curious may wonder how helpers() works here, and though it’s slightly tangential, you’ll see it is similarly simple.

  def helpers(helper_module=nil, &block) 
    @helpers = helper_module || Module.new(&block) 
  end

Though I won’t get into it here, fun tricks can be done with anonymous modules as well. Can you think of any that are particularly interesting? If so, let me know in the comments.

Although I only showed a part of the picture, you might want to check out the rest of Fatty’s source. I call it a ‘67 line replacement for Ruport’, which is a major exaggeration, but it is really surprising how much you can get out of a few dynamic Ruby tricks when you combine them together properly. A lot of these ideas were actually inspired by the Sinatra web framework, so that’s another project to add to your code reading list if you’re looking to learn new tricks.

Anyway, I’m getting off topic now, and it’s about time to wrap up anyway. I’ll go on one more tiny tangent, and then send you on your way.

Shortcutting with Struct

With all this talk about using anonymous sub-classes, I can’t help but recap one of the oldest tricks in the book. The method Struct.new can be handy for shortcutting class creation. Using it, the very first example in this post could be simplified down to:

class Point < Struct.new(:x, :y)
  def distance(point)
    Math.hypot(point.x - x, point.y - y)
  end
end

The constructor and accessors are provided for free by Struct here. Of course, the real reason I mentioned this was to get you thinking. If Struct.new can work this way, and we know that Class.new can accept a block definition that provides a closure, what other cool uses of parameterized subclasses can we cook up?

Please Share Your Thoughts

I wrote this article in hopes that it’ll be a jumping off point for discussion on more cool tricks I haven’t seen before, or failing that, ones that other readers haven’t seen before. While there certainly is a lot of nasty, scary looking “meta-programming” out there that makes people feel like this stuff is hard and esoteric, there are many techniques that lead to simple, elegant, and beautiful dynamic code. Please let me know what you think of these techniques, and definitely share one of your own if you’d like.

Rails Modularity for Lazy Bastards

gregory.t.brown@gmail.com (Gregory Brown) — Thu, 16 Apr 2009 04:31:00 -0000

When we develop standalone systems or work on libraries and frameworks, modularity seems to come naturally. When something seems to gain a life of its own, we pull it off into its own package or subsystem to keep things clean. This is a natural extension of the sorts of design decisions we make at the object level in our software, and helps us work on complicated problems, often working alongside other hackers, without losing our wits.

It seems a bit surprising that these helpful guiding principals can often evaporate when we bring our software to the web. Sure, we may make use of plugins and gems for foundational support, but if you take a good look at a Rails application that has more than 50 models or so, you’ll be hard pressed to find a unified purpose behind all that logic.

However, if you try to break things down into core sets of functionality, you may find that certain vertical slices can be made that allow you to break out bits of functionality into their own separate focus areas. For example, you may discover that part of your application is actually a mini CRM system. Or maybe you’ve snuck in a small reporting system without noticing it consciously. The list goes on, but the underlying idea here is that the larger a system gets, the harder it is to define its core purpose.

While splitting out these subsystems may seem like the obvious choice in a standalone application, there seems to be a certain amount of FUD about this strategy when it comes to the web. This probably originates from a time before REST, in which interaction between web applications was overly complex,making the costs of fragmentation higher than the benefits of a modular architecture. These days, we live in better times and work with better frameworks, and should reap the benefits that come along with it.

But actions speak louder than words, so let’s take a look at some of the underlying tech and how to use it. Building on the CRM scenario, I’ll start by showing how to access a Customer model from another application using ActiveResource.

Sharing Model Data via ActiveResource

Suppose that we’ve got a CRM system that has a Customer model that has a schema that looks something like this:

  create_table :customers do |t|
    t.string :first_name
    t.string :last_name
    t.string :email
    t.string :daytime_phone
    t.string :evening_phone
    t.timestamps
  end

With this, we can do all the ordinary CRUD operations within our application, so I won’t bore you with the details. What we’re interested in is how to accomplish these same goals from an external application. So within our CRM system, this essentially boils down to simply providing a RESTful interface to our Customer resource. After adding map.resources :customers to our config/routes.rb file, we code up a CustomersController that looks something like this:

  class CustomersController < ApplicationController
  
    def index
      @customers = Customer.find(:all)
      respond_to do |format|
        format.xml { render :xml => @customers }
        format.html
      end
    end
 
    def show
      customer = Customer.find(params[:id])
      respond_to do |format|
        format.xml { render :xml => customer.to_xml }
        format.html
      end
    end
 
    def create
      customer = Customer.create(params[:customer])
      respond_to do |format|
        format.html { redirect_to entry }
        format.xml { render :xml => customer, :status   => :created, 
                                              :location => customer }
      end
    end
 
    def update
      customer = Customer.update(params[:id], params[:customer])
      respond_to do |format|
        format.xml { render :xml => customer.to_xml }
        format.html
      end
    end
 
    def destroy
      Customer.destroy(params[:id])
      respond_to do |format|
        format.xml { render :xml => "", :status => 200 }
        format.html
      end
    end
 
  end

This may look familiar even if you haven’t worked with ActiveResource previously, as it’s basically the same boiler plate you’ll find in a lot of Rails documentation. In the respond_to block, format.xml is what matters here, as it is what connects our resource to the services which consume it. The good news is we won’t have to actually work with the XML data, as you’ll see in a moment.

While there are a few things left to do to make this code usable in a real application, we can already test basic interactions with a secondary application. Using any other rails app we’d like, we can add an ActiveResource model by creating a file called app/models/customer.rb and setting it up like this:

  class Customer < ActiveResource::Base
    self.site = "http://localhost:3000/"
  end

Now here comes the interesting part. If you fire up script/console on the client side application that is interfacing with the CRM system, you can see the same familiar CRUD operations, but taking place from a completely separate application:

  >> Customer.create(:first_name => "Gregory", :last_name => "Brown")
  => #<Customer:0x20d2120 @prefix_options={}, @attributes={"evening_phone"=>nil, "updated_at"=>Thu Apr 16 03:53:59 UTC 2009, "daytime_phone"=>nil, "id"=>1, "first_name"=>"Gregory", "last_name"=>"Brown", "created_at"=>Thu Apr 16 03:53:59 UTC 2009, "email"=>nil}>
 
  >> Customer.find(:all)
  => [#<Customer:0x20a939c @prefix_options={}, @attributes={"evening_phone"=>nil, "updated_at"=>Thu Apr 16 03:53:59 UTC 2009, "daytime_phone"=>nil, "id"=>1, "first_name"=>"Gregory", "last_name"=>"Brown", "created_at"=>Thu Apr 16 03:53:59 UTC 2009, "email"=>nil}>]
 
  >> Customer.find(1).first_name
  => "Gregory"
 
  >> Customer.delete(1)
  => #<Net::HTTPOK 200 OK readbody=true>
 
  >> Customer.find(:all)
  => []

While the interface and behavior isn’t downright identical to ActiveRecord, it bears a striking resemblance and allows you to retain much of the functionality that is needed for basic data manipulation.

Now that we can see the basic functionality in action, let’s go back and fix a few key issues. We definitely want to add some sort of authentication to this system, as it is currently allowing any third party application to modify and destroy records. We also will most likely want a more flexible option for locating services than just hard coding a server address in each model file. Once these two things are in place, we’ll have the beginnings of a decentralized Rails based application.

API Keys with HTTP Basic Authentication

I want to preface this section by saying I’m typically not the one responsible for any sort of security hardening in the applications I work on. That means that I’m by no means an expert in how to make your applications safe from the malignant forces of the interweb. That having been said, what follows is a simple technique that seems to work for me when it comes to slapping a simple authentication model in place.

First, in the app that is providing the service, in this case, our fictional CRM system, you’ll want something like this in your ApplicationController:

  def basic_http_auth
    authenticated = false
    authenticate_with_http_basic do |login, password|
      if login == "api" && password == API_KEY
        authenticated = true
      end
    end
 
    raise "Authentication failed" unless authenticated
  end

Here, API_KEY is some shared secret that is known by both your service providing application, and any client that wishes to use your service. In this blog post, I’ll be using the string “kittens”, but you’ll obviously want to pick something longer, and with significantly more entropy.

After dropping a before_filter in your CustomersController that points to basic_http_auth, you’ll need to update your ActiveResource model definition.

  class Customer < ActiveResource::Base
    self.site = "http://localhost:3000/"
    self.user = "api"
    self.password = "kittens"
  end

If you forget to do this, you won’t be able to retrieve or modify any of the customer data. This means that any application that does not know the shared secret may not use the resource. Although this is hardly a fancy solution, it gets the job done. Now, let’s take a look at how to make integration even easier and get rid of some of these hard coded values at the per-model level.

Simplifying Integration

So far, the work has been pretty simple, but it’s important to keep in mind that if we really want to break up our applications into small, manageable subsystems, we might need to deal with a lot of remote resources.

Pulled directly from some commercial work I’ve been doing with Brad Ediger of Madriska Media Group (and of Advanced Rails fame), what follows is a helper file that provides two useful features for working with remote resources via ActiveResource:

  require 'yaml'
  require 'activeresource'
 
  class ServiceLocator
 
    API_KEY = "kittens"
 
    def self.services
      return @services if @services
      config_file = File.join(RAILS_ROOT, %w[config services.yml])
      config = YAML.load_file(config_file)
      @services = config[RAILS_ENV]
    end
 
    def self.[](name)
      services[name.to_s]
    end
  end
 
  def Service(name)
    Class.new(ActiveResource::Base) do
      self.site = "http://#{ServiceLocator[name]}"
      self.user = "api"
      self.password = ServiceLocator::API_KEY
    end
  end

The ServiceLocator part was Brad’s idea, and it represents a simple way to map the URLs of different services to a label based on what environment you are currently running in. A basic config/services.yml file might look something like this:

  development:
    crm: localhost:3000
    reports: localhost:3001

  production:
    crm: crm.example.com
    reports: reports.example.com

This is nice, because it allows us to configure the locations of our various services all in one place. The interface is very simple and straightforward:

  >> ServiceLocator[:crm]
  => "localhost:3000"

However, upon seeing this feature, I decided to take it a step farther. Though it might sacrifice a bit of purity, the Service() method is actually a parameterized class constructor that builds up a subclass filling out the API key and service address for you. What that means is that you can replace your initial Customer definition with this:

  class Customer < Service(:crm)
    # my custom methods here.
  end

Since Rails handles the mapping of resource names to class names for you, you can easily support as many remote classes from a single service as you’d like this way. When I read this aloud in my head, I tend to think of SomeClass < Service(:some_service) as “SomeClass is a resource provided by some_service”. Feel free to forego the magic here if this concerns you, but I personally find it pleasing to the eyes.

Just Starting a Conversation

I didn’t go into great detail about how to use the various technologies I’ve touched on here, but I’ve hopefully provided a glimpse into what is possible to those who are uninitiated, as well as provided some food for thought to those who already have some experience in building decentralized Rails apps.

To provide some extra insight into the approach I’ve been using on my latest project, we basically keep everything in one big git repository, with separate folders for each application. At the root, there is a shared/ folder in which we keep some shared library files, including some support infrastructure for things like a simple SSO mechanism and a database backed cross-application logging system. We also vendor one copy of Rails there and simply symlink vendor/rails in our individual apps, except for when we need a specific version for a particular service.

The overarching idea is that there is a foundational support library that our individual apps sit on top of, and that they communicate with each other only through the service interfaces we expose. We’ve obviously got more complicated needs, and thus finer grained controls than what I’ve covered in this article, but the basic ActiveResource functionality seems to be serving us well.

What I’d like to know is what other folks have been doing to help manage the complexity of their larger Rails apps. Do you think the rough sketch of ideas I’ve laid out here sounds promising? Do you foresee potential pitfalls that I haven’t considered? Leave a comment and let me know.

Welcome to the RBP blog

gregory.t.brown@gmail.com (Gregory Brown) — Tue, 07 Apr 2009 17:02:00 -0000

Hello, and welcome to the Ruby Best Practices blog. I am happy to announce this new collaborative writing project, along with the great team that’ll be running it. A couple weeks ago I put out a call for volunteers to help me provide a new community resource for discovering and discussing best practices in Ruby, and now, we’re ready to get rolling.

In addition to myself: James Britt, Kirk Haines, Robert Klemme, Jeremy McAnally, Sean O’Halpin, Magnus Holm and Lakshan Perera round out the team. I am absolutely thrilled to have such a diverse and talented group to work with, and I can’t wait to see the content that we’ll produce together.

The general theme we’ve agreed upon for this blog is that each post should exhibit Ruby code that we can be proud of. We want to expose best practices through practical examples, so you will surely see a lot of open source code being discussed here. We want to give you less of “Here’s six great Rails plugins” and more of “Examples of Connascense in ActiveRecord”, or “Common Pitfalls in DSL Design, and How to Avoid Them”. Not every single post will be focused directly on best practices and idioms, but all will contain them.

This will be a code and high-level design heavy blog. We don’t plan to bore you with war stories or skimp on the technical value of our content to promote our latest cute but useless hack. That having been said, we plan to have fun while we write, and the occasional diversion will happen as a result. However, it’s safe to say that our content will be geared more towards the motivated developer looking to improve her craft rather than the general “plzgivemethecodes” crowd. If that sounds like your kind of thing, I think you’ll really enjoy this blog.

The blog engine we’ve decided to use is Korma which I’m sure you’ll hear more about in the near future. It was designed specifically to run this blog, is git based, and gives us a lot of cool features that we wanted to make sure to have in place before launch. Because we want to provide both the authors and the readers freedom to choose which content they are interested in, it is possible to subscribe to individual author feeds on this blog. This means that if you like 6 of us, the two you don’t like won’t bother you. Of course, we hope you like us all.

Over time, we’ll eventually begin accepting outside contributions to this blog, likely through something as simple as a fork and pull request on github. This means if you have an idea for an article that you’d like to see here, we may be accepting new content from third party contributors soon. However, before we can do that, we need to wait for the dust to settle, so look for an announcement in a few weeks.

It may take us a little while to work out the kinks in our blogging software. We want to keep things simple, but there still might be a few bugs here or there. If you run into problems using this blog, please email gregory.t.brown at gmail.com and let me know.

I think that pretty much wraps up the welcome letter. New posts should be cycling in within the next couple days, and we hope to remain active moving forward. Thanks for checking out this new blog, and happy hacking!

Ruby Best Practices

Ruby Mendicant University is a Go!

IDEA: Ruby Mendicant University

The Idea

Funding

Schedule

Why Me?

What do you think?

If you want to see the wizard, go to Oz.

Red Dirt RubyConf: Your ticket to Oz

rubyproblems.com is now live!

Full Book Now Available For Free!

Manuscript and Production Files

But I finished the RBP book and I want more! What should I do?

Disclaimer

Ruby Tuesdays: RBP Chapter 7

Progress To Date

How To Read RBP

Today’s Topic

For Your Consideration

Ruby Tuesdays: RBP Chapter 6

Progress To Date

How To Read RBP

Today’s Topic

For Your Consideration

Ruby Tuesdays: RBP Chapter 5

Progress To Date

How To Read RBP

Today’s Topic

For Your Consideration

Ruby Tuesdays: RBP Chapter 4

Progress To Date

How To Read RBP

Today’s Topic

For Your Consideration

RBP is useless without you

Weekend Reading: RBP Chapters 2-3

Today’s Topics

For Your Consideration

Weekend Reading: RBP Chapter 1

Today’s Topic

For Your Consideration

Reflections from "The Compleat Rubyist"

The Training

Ruby Versions and Implementations

Meta-programming

Testing

Style and Substance

The Event

The Future

Learning From Bad Ideas

Continuations are Evil?

Your Homework

Be Nice and Have Fun

Should I Tap that Hash? (Ruby 1.9 Style)

Object#tap, a seemingly benign addition.

Object#tap as an alternative to ActiveSupport’s returning

Tapping that Hash.

A Gentle Reminder

25th Post!

Code Blocks: Ruby's Swiss Army Knife

Working with Enumerable

Using Blocks to Abstract Pre- and Postprocessing

Blocks as Dynamic Callbacks

Blocks for Interface Simplification

Things to Remember

Did you enjoy this post?

The Decorator Delegator Disco

A quick demo

The Decorate module

An alternative to core extensions

Pros for this solution

Cons for this solution

Conclusions

Quack Attack: Making Your Code More Rubyish

Guidelines For Making Your Code More “Rubyish”

RubySpec as a Community Resource (Interview w. Brian Ford)

In an ideal world, what would the RubySpec project do for the Ruby community?

With everything changing so fast, I imagine keeping the specs up to date is a constant struggle. How do implementers keep up with what’s going on?

I would really love to make RubySpec a household name in the general Ruby community. The project I’m breaking ground on now (called Unity), will hopefully help do this. What sort of information do you think is most valuable to pull out from RubySpec, and who do you see benefiting from it?

The `Decorate` module