Schneems

I’ve heard this re-framed again and again by many different programmers from @wycats at Ruby conf to @dhh in his parlay letter:

I consider this [the ease of getting started], like maintainability, to be a side effect of good, simple design.

I think this is a great way of looking at the “beginner” problem, but it doesn’t give much guidance. What exactly is good design for advanced developers? Why is it also good for beginners? Who counts as a beginner? Is a .NET dev with 5 years of industry experience learning rails lumped into the same category as a someone who had never previously viewed-source on a webpage?

In the Beginning

Let’s take it back a bit, to the era before one click purchases, and github signup buttons. The realm was ruled by the textbox and it’s mighty accomplices radio buttons, text areas, and submit buttons. Signing up for a new web app was a lesson in finger cramps. Eventually some people were clever enough to figure out that fewer fields meant fewer interactions, and less fatigue. This of course lead to fewer people dropping off and higher sign-up numbers. Good for the business, who now has more users. Good for you, who now has to type. In the end all they needed was a password and an email, the rest was just details.

What do web forms have to do with advanced programming? Everything. It doesn’t matter if you were browsing the BBS on a 28.8k or you just got your first taste of the Internet over AOL, you had to go through the same interaction. Experience was irrelevant. There was no “click here if you understand the internet” signup option. So when the pain of signing up for many many services by the elite trickled down to help the newbs signing up for their first service: every won.

Anectdotes aside, this is how coding for interaction should be. Build for the pros, don’t forget the nos. What can we as developers take away from the signup form? Treat each user interaction as a barrier to entry and productivity, slash cut and simplify until you can’t be simpler, and treat the interface as a tool to reduce activation energy.

PROTIP: Look for heavy process and cut it down to size

Sometimes the simplicity can come from an internal structure, let’s take a look at how re-thinking how routes are groked led us to a more productive programmer and eventually a smarter “beginner”.

Simplicity in Action: Sextant

A Sextant is an ancient tool for finding your route via the stars. My program Sextant is a tool for finding your rails routes via your browser. I started the project to save me from the pain of rake routes to slash my waiting time (counted in agonies per command, of course) from 20 to 0.

What started as a simple tool for saving time has since ballooned into a new way to visualize and think about a core part of our Rails coding experience, with over 39 thousand downloads. The key to it’s success was identifying that extra step that wasn’t needed, the boot time of the rails app. Now that sextant is shipping with Rails 4 we can start the process over again. What else isn’t needed, or what is missing?

The Evolution of an Interface

Once we got the routes into the browser we’ve now got a powerful set of interaction tools to work with, namely html and javascript. I was able to clean up the visuals of the routes a bit, but it always bothers me when the computer knows the answer to something and yet makes me do the work. Named routes which are a commonly used element in the views, are listed not as they are intended to be used, but instead only have their prefixes in the output. So instead of new_users_path I’ll often type new_users into a view by accident when I’m tired or distracted. When I hit refresh the page I see my problem, I forgot to do my mental math and add the _path suffix. When you’re already tired, already frustrated, just trying to ship a feature these seemingly small hoops to jump through grow ever larger with each mistake made. Why not remove them entirely?

The solution is to add this info into the view by displaying the full named route helper:

I think this is great. But why, what makes this a good idea?

‘Don’t make me think’

Rails is famously convention over configuration. This saves you, the developer, countless hours debating where to put your files or and what to name your folders. While this eliminating these extra steps is a great thing, something can get lost in the translation:

The first thing this current class of students asked me is “Where can I find the document that describes all of the Rails conventions.” - @steveklabnik

As you’re removing steps, if you miss some, then you’re secretly adding a hidden step to Google for for awhile. This Google tax only comes to: the new, the uninformed, the tired, and the overworked programmer trying to ship at the last minute. It’s easy to forget once you know the missing step by heart. This is why being explicit with route helpers in Sextant makes an impact. We took the hidden step “add _path to the end of these” and made it explicit without losing any information (you can still see that _url is an option):

PROTIP: Mental math leads to errors, where can we be more specific?

While you’re refining and iterating and slashing steps, don’t forget to keep context front and center. If you’re looking for places where you might need better docs, or more accessible information. I recommend you keep a …

Cheat Sheet

I use Evernote to keep track of the text snippets and docs links I end up finding useful. Not only does it help to organize my thoughts while I’m having issues, I can search it later if I run into the same problem, and even better when I’m bored or looking for something to productively procrastinate with, these notes are great places to see if we could add more docs, take away steps, or remove some mental math.

Design for All

If I can make my interface so simple it only needs one step, maybe one day we can eliminate the need entirely. This is exactly how automation is born and thrives. While it’s obvious saving developer time is a good thing, why had no one done this before, and how can you build better software for all levels?

• Keep a cheat sheet
• Look for duplicate or un-needed steps
• Look for long complicated processes
• Look for missing docs or implied information

Get up and make a difference, work with more beginners, contribute to open source and help close the gaps.

Richard “@schneems” (pronounced like Schnapps) Schneeman writes Ruby code for @heroku and teaches Rails at the University of Texas.

I wrote this wizard controller library that people seem to really dig called Wicked. It works well to build after signup wizards and to incrementally build objects for the database but there is one thing it didn’t do very well until now: allow you to change the text in your wizard url’s quickly and easily.

If you’re new to Internationalization (I18n) it’s a process of making your website look native in more that one language. With the newly released Wicked you can translate your wizard urls or simply use it to change your custom urls in one language with no code changes. Check it out:

Internationalization of URLS (I18n)

If your site works in multiple languages, or if you just want more control over how your URL’s look you can now use I18n with wicked. To do so you need to replace this:

include Wicked::Wizard

With this:

include Wicked::Wizard::Translated

This will allow you to specify translation keys instead of literal step names. Let’s say you’ve got steps that look like this:

steps :first, :second

So the urls would be /after_signup/first and /after_signup/second. But you want them to show up differently for different locales. For example someone coming form a Spanish speaking locale should see /after_signup/uno and after_signup/dos.

To internationalize first you need to create your locales files under config/locales such as config/locales/es.yml for Spanish. You then need to add a first and second key under a wicked key like this:

es:
  hello: "hola mundo"
  wicked:
    first: "uno"
    second: "dos"

It would also be a good idea to create a english version under config/locales/en.yml or your english speaking friends will get errors. If your app already uses I18n you don’t need to do anything else, if not you will need to make sure that you set the I18n.locale on each request you could do this somewhere like a before filter in your application_controller.rb

before_filter :set_locale

private

def set_locale
  I18n.locale = params[:locale] if params[:locale].present?
end

def default_url_options(options = {})
  {locale: I18n.locale}
end

For a screencast on setting up and using I18n check out Railscasts. You can also read the free I18n Rails Guide.

Now when you visit your controller with the proper locale set your url’s should be more readable like /after_signup/uno and after_signup/dos.

Wicked expects your files to be named the same as your keys, so when a user visits after_signup/dos with the es locale it will render the second.html.erb file.

Important: When you do this the value of step as well as next_step and previous_step and all the values within steps will be translated to what locale you are using. To translate them to the “canonical” values that you’ve have in your controller you’ll need so use wizard_value method.

For example, if you had this in your controller, and you converted it to a use Wicked translations, so this will not work:

steps :confirm_password, :confirm_profile, :find_friends

def show
  case step
  when :find_friends
    @friends = current_user.find_friends
  end
  render_wizard
end

Instead you need to use wizard_value to get the “reverse translation” in your controller code like this:

steps :confirm_password, :confirm_profile, :find_friends

def show
  case wizard_value(step)
  when :find_friends
    @friends = current_user.find_friends
  end
  render_wizard
end

The important thing to remember is that step and the values in steps are always going to be in the same language if you’re using the Wicked translations. If you need any values to match the values set directly in your controller, or the names of your files (i.e. views/../confirm_password.html.erb, then you need to use wizard_value method.

Custom URL’s

Very similar to using I18n from above but instead of making new files for different languages, you can stick with one language. Make sure you are using the right module:

include Wicked::Wizard::Translated

Then you’ll need to specify translations in your language file. For me, the language I’m using is english so I can add translations to config/locales/en.yml

en:
  hello: "hello world"
  wicked:
    first: "verify_email"
    second: "if_you_are_popular_add_friends"

Now you can change the values in the URL’s to whatever you want without changing your controller or your files, just modify your en.yml. If you’re not using English you can set your default_locale to something other than en in your config/application.rb file.

config.i18n.default_locale = :de

Important: Don’t forget to use wizard_value() method to make sure you are using the right cannonical values of step, previous_step, next_step, etc. If you are comparing them to non wicked generate values.

Custom crafted wizard urls: just another way Wicked makes your app a little more saintly.

Richard @schneems (pronounced sorta like Schnapps), loves writing gems and works for Heroku. If you enjoy the wicked gem consider watching the repo or telling your friends.

If you’re in the Ruby world, you’ve likely heard about mruby, Matz’s latest experimental Ruby implementation. What I bet you didn’t know is that you can run mruby on Heroku right now. As a matter of fact you can run just anything on Heroku, as long as it can compile it into a binary on a Linux box.

If you’re new to mruby, or to compiling binaries take a look at my last article Try mruby Today. I cover getting mruby up and running on your local machine. If you are already up to speed then follow along as we use vulcan to package mruby as binary, wrap it up in a custom buildpack and then launch an app to use mruby on the Heroku cloud.

Continue Reading …

Yesterday

If you missed it yesterday we announced official support for Ruby 2.0.0 Preview1, and announced the dates for our developer conference, Waza 2013, including the Waza call for Speakers.

I’m finally wrapping up my UT on Rails series. While people have been getting close to the end of the course, I’ve gotten the question “Now what?” plenty of times. Now that you’ve spent 40+ hours pouring over videos, exercises, and quizzes where do you go from here? To answer this question I made a short video. But first, the last exercise of the course:

Reddit on Rails: Part 3

This week we wrap up our Reddit on Rails exercise series by adding styling to our project, full text search, and some much needed integration tests. What are you waiting for go start on the exercise.

Where Do We Go Now

A programming course can’t make you a good programmer, watch this video to learn where to go from here. Don’t stop now, you’re so close to doing great things…

Additional Resources

• reddit.com/r/ruby
• Ruby weekly
• Rails Casts
• Metaprogramming Ruby [book]
• The Pragmatic Programmer: From Journeyman to Master [book]
• New Programmers Survival Manual [book]
• Programming Ruby [The Pickaxe book]

Don’t forget to follow me on twitter @schneems and tumblr. Though the class might be over, I still talk about Ruby and Rails quite a bit. Thanks, and see you on the internets.

Ruby dominates the web: running popular sites like Github, Heroku, and Living Social. But why should web developers get to have all the fun? Wouldn’t it be great if game developers, embedded systems engineers, or anyone else could use the beautiful syntax of Ruby in their C programs? Lucky for us, that’s exactly what mruby plans to do…

continue reading my article on Rubysource: try mruby today

Exceptions suck. When you are getting started on a project there is nothing worse than clicking that button, hitting enter, and then watching your software fall flat on its face. It might sound odd - then - if I were to say, more errors in your life could be a good thing.

For the past few months I’ve been working with new programmers at the University of Texas and through Rails Girls. It’s humbling to say the least, to watch a new user fumble around with Ruby and Rails. They run into problems you’ve either long forgotten about, or are so used to, you’re numb to them. After having to tell the 15th-thousand student to migrate their database to get rid of a method_missing error I thought to myself “there has to be a better way”. Essentially our system knows exactly what the problem is, it knows that you’ve got pending migrations so how can we let a programming language talk to its users? It would be so simple if Rails could just jump out, call us on the phone and tell us to “migrate our database to fix this error”, but sadly VOIP and speech generation aren’t standard libraries (yet). Since that option is out the door, how can we talk to programmers new and old alike and tell them this important message. It’s pretty simple, we just raise a little hell.

Previously if you added an admin column to your user table via a migration and forgot to run it then refreshed a page you would still get an error, but the error message was misleading at best:

"NoMethodError: undefined method `admin?' for #<User:0x007ff1d4bfa018>""

It tells us that there is an issue with User, but doesn’t give us any clues why exactly that method is undefined. With my patch a middleware checks for pending migrations in development mode and we can raise a much more useful error:

"Migrations are pending run 'bundle exec rake db:migrate RAILS_ENV=development' to resolve the issue"

Now when I get this error I don’t cringe or rage post on stack overflow, I take delight knowing that the framework I’m using is gently coaxing me back in between the lines.

I’ll give you another example, what do you think about this error:

"undefined method `model_name' for NilClass:Class"

Not very helpful. Turns out that’s the error you get when you accidentally pass a nil object to a form_for:

<%= form_for @user do |f| %>
  # ...

I’ve seen that error so many times, I can spot it from across the room. The thing that gets me is that Rails knows you’re getting into an exceptional situation as soon as you pass in a nill or empty object into form_for but it wasn’t checking, instead it just passed whatever bad arguments you passed in around until something errored out somewhere in the call stack. So now we’ve got a bad error message and a stack trace that leads us down a rabbit hole, can we fix it? Sure, a simple object.blank? check and we can raise a meaningful error message:

raise "First argument in form cannot contain nil or be empty" if object.blank?

So now you know that the error came from form_for as a result of passing in nil or an empty array. All that is left is for you to fix it.

I was first introduced to this style of raising early errors after attending a Avdi’s talk about Confident Ruby at RailsConf 2011. If you weren’t fortunate enough to attend one of his talks you can still read his ebook.

Raising early errors with good messages can help immensely, but we can do more. If every time you get a routing error, you have to run $ rake routes why not put rake routes in your error page. If leaving out arguments causes an error, tell the programmer exactly what they are missing. Even for common sense debugging tips, it can still never hurt to remind someone to check the logs.

These days a heavy emphasis is placed on good documentation as it should be, but docs are only good when you’re looking at them. By writing better errors we are creating living documentation that comes to you exactly when you need it the most. Good error messages are like lessons learned scaled out to thousands of developers.

Next time you find yourself confused when you’re programming, write down any error messages you get. Keep it in evernote or a text file, and when you figured out what went wrong and how to fix it, ask yourself if there was a better way to experience that error. Did Rails have enough information to know what you did wrong? If not, why? If so, why didn’t you get a better error message? Don’t just sit back, relax and let errors pass you bye, go out there - get mad - write code - raise “hell”.

Richard works for Heroku on the Ruby Team and teaches rails classes at the University of Texas. If you like errors as much as he does, chat him up on the twitters @schneems. These error messages and more are available starting with Rails 4.

We are close to wrapping up our 10 week Rails Course. This week we will cover a handful of topics commonly encountered in Rails projects. We then wrap up with part 2 of our Reddit on Rails exercise!

By now you should be hard at work on your personal projects. The students in the course just presented in front of the class with some live demos and a brief intro to to the problems their app were solving. Maybe set aside some time this week to show someone your progress, block off 5 minutes and describe what goal you are working towards, the current state of the project (is it almost done, just getting started, needs UI, etc.), and then show them a quick demo of the app. Explain what type of feedback you are looking for (conceptual, design, usability, etc.) and see what they have to say.

As we are wrapping up the course you need to be focused on learning as much as you can, but also making sure you have the tools to succeed after the class is over.

Rails Cookies and Sessions

Sending Email with Rails

Full Text Search

Background Tasks

Exercise

This week we pick up where we left off last week, building a Reddit clone in Rails: Reddit on Rails part 2

Welcome back, this week we’re going to tackle some important concepts in Ruby like Dealing with Nil and using Modules in Ruby. We are also going to cover importing data from a spreadsheet, rake, rubygems, bundler, and talk a little about Rail’s testing ecosystem.

Recap of week 7. Then take the Quiz and review the Solutions

Before we get started there have been quite a few questions about why not use a simpler solution than Rails, so I recorded a quick explanation of Simple Versus Hard and why we might want to pick a more complex tool to solve our complex problems

Rails Testing Ecosystem

As your app gets more complex testing components gets even more critical. In this video we cover the basics of what testing does, and then we talk about a few tools we can use to automate tests in our Rails code.

Rubygems & Bundler

Rails is a rubygem, but what is a rubygem? We’ll cover that in this video as well as exactly what bundler does, and why we should always keep the Gemfile and Gemfile.lock in our source control.

Import data into Rails from a Spreadsheet

By popular demand learn how to read spreadsheet data into Ruby and then put it in Rails.

Intro to Rake

Rake is a useful command line tool, learn how to write your first rake task and how to use Rake together with Rails.

Dealing with Nil

As a Ruby programmer the most common value you’ll encounter will be nil. It’s our duty to be on constant watch for nil and make sure it doesn’t reek havoc on our code. This video will introduce you to some boolean logic we can use to defend against the tyranny of nil. We’ll then cover using nil? and empty? as well as several custom Active Support methods we can use from Rails to help guard against nil. Nil isn’t all bad, at the end we’ll see how we can use this functionality of nil to populate variables only if they don’t exist. We’ll use this to find or create a user in Rails.

Using Modules in Ruby

Modules are an extremely important part of the Ruby ecosystem. Learn how to mix in methods into a Ruby class using modules in this introductory video.

Exercise

This week we’ll start a Hero’s journey to build a site similar to Reddit. You’ll need to use everything we’ve learned so far. This isn’t a follow along copy and paste tutorial, this is how I work when I’m making websites. Good luck, you’ll need it. Building Reddit on Rails.

We’ve covered models, views, routing, and briefly introduced controllers. This week we’re taking the deep dive into controllers, talking about what they can do, and how we want to use them. Last week we talked about wiring things together with routing. You can watch the Recap then do the Quiz and once you’re done check out the Quiz Solution.

Before we get started talking about controllers, first we’ll introduce Ruby Variable Scope. We’ve used local variables and constants in our code, and now it’s time to introduce instance variables and discuss their differences, and why you might want to use one over another.

Now that you’ve seen how we can use instance variables, we will use one in our controller to move some SQL logic from the view to the controller. This is important for keeping our views clean and focused on presentation logic. It will also help us later when we look into the other things a controller can do.

Database logic in controllers

Now that we’re pulling data from our database in our controller we can render, redirect Filter & Format from our controllers. Check out this video to find out what these are and how we can use them to help build our app.

This last video on Rails URL Helpers covers using $ rake routes to get info on routes and how we can use different url helpers in our app.

In the exercise we’ll be nesting a few if, def and class definitions in our code. It can be easy to lose your place and difficult to remember what end corresponds to which line. To help out you can watch a quick video on my End of the line, programming trick with the sublime text editor.

Exercise

In this exercise we’re fleshing out the app we worked with later to add full CRUD and move logic from the view to the controller. Just fork and clone the repo and go through the readme!

Thanks for following along, for up to date ruby info you can catch me @schneems, and can subscribe to my youtube channel

In week one we learned about storing data and using databases. In week 2 we saw how we can model relationships with databases, and use those relationships with Ruby and Active Record to build models in Rails. This week we start out with a quick Recap of last week followed by a Quiz. Once you finish the quiz you can check out the Quiz Solutions.

This week we will be focused on building cool things with Pure Ruby (no Rails). We’re going to cover some Ruby basics, and then dive into an exercise where we build an HTML generator using only Ruby. The students really enjoyed the exercise, and got quite a bit out of it, so you shouldn’t skip it. Even if you’ve been using rails for years, the exercise might give you new insight into how exactly some of that Rails magic works.

We’ll also cover using GIT and you’ll need that for the exercise. Get ready cause here comes some serious learning.

Week 3 Videos

Introduction of topics covered:

Ruby arrays and iterating over them with each and map methods:

Using the functions found in Ruby’s STDlib:

Using the ERB library from Ruby’s STDlib to generate HTML:

Finally an Introduction to using GIT. We cover the basics of using a source control management software (GIT) as well as the mechanics of saving files, adding them to a repo, and committing them. GIT is a valuable skill to have, and is needed for the exercise.

Week 3 Exercise

First you need to Fork and Clone my Generating HTML views with pure Ruby repository . Then you can follow along with the exercises in the readme.

If you’re thinking about skipping the exercise, don’t. Programming is a language that you have to learn by using it. As always if you get stuck try googling, or posting onto StackOverflow.

The only difference is that I won’t be grading your work, so don’t submit a pull request when you’re done.

Good luck and happy coding.

Fin

Next week we’ll be putting what we learned about databased backed models and view generation together to start building a fully functional app. Stay tuned, subscribe to this tumblr blog, or youtube channel and let me know if you’ve got any comments @schneems