Searching for the Perfect Inline Code Documentation Tool

Even amongst programmers I’m weird because I have an intense love for documentation. No, that doesn’t mean I overly comment my code, or that you’ll catch me browsing happily through the product requirements document during my coffee break. I should be more specific.

I have an intense love automatic documentation generation. Nothing makes me more tickled pink than seeing code and documentation living side by side in perfect harmony. I hate seeing documentation put on the company intranet only to diverge from the code it’s supposed to explain as the days go past. I hate hitting my head against a brick wall as I’m pouring through the source code trying to understand an API because at no point does it mention that it’s documented in a Word doc in another directory.

This is my rule of programming: documentation should live beside the code it documents, in the comments, especially if it’s API documentation. If your language of choice doesn’t already have some kind of automatic code generation tool then you’re probably using the wrong language.

How to Explain RSS to Normal People – 2008 Edition

As a geek who enjoys spending too much time on the internet, I like RSS almost as much as delicious toast. As a blogger, RSS is the shiznitz because it lets you consume a lot more information and it makes it easier for other people to read your blog without having to drop by every few days to see if you’ve written something new.

For something so useful, it’s pretty hard to explain why people should use RSS. Lots of people try to do it. This is my take on it. It’s 2008 and explaining RSS should be much simpler because if you’ve used Facebook, then you’ve used RSS.

RSS for Normal People (who use Facebook)

I Can Has Ruby?

I seem to have finagled my way into getting to program in Ruby almost full time at work. One day you’re just reading raganwald, labnotes and gilesbowkett and then the next day you’re doing guerrilla adoption of a new language. Obviously, the internet is a gateway drug. I tried out Ruby mainly as a way of increasing my own job satisfaction after I had heard so many good things about it.

So far it’s working.

Because I’m using Ruby for several hours a day, I’ve decided to start up a tumblr account as a link dump for all the things I’m finding out as I’m learning Ruby.

rubeh.tumblr.com

Related Posts

• How to Install the Exception Notifier Plugin with Ruby on Rails
• Getting Started with Ruby on Rails – Week 3 – Testing
• Getting Started With Ruby on Rails – Week 2
• Getting Started With Ruby on Rails – Week 1

How to delete your Tumblr tumblelog with TumblrCleanr

Tumblr is rapidly becoming my favorite free blogging platform (more so than Blogger/WordPress.com) because of all the things they do correct:

• RSS feed importing (up to 5)
• free domain name support
• free CSS/theme support
• Google Analytics support
• javascript widget support
• keeping it simple

(You can read more about Tumblr’s Pro and Cons in this post I wrote for Lorelle on WordPress)

However, there’s one feature that’s missing: how do you delete your Tumblr? At some point you might want to destroy all traces of your tumblr (privacy concerns, or you want to use it for something else) and there isn’t an option to do that — other than click the delete button on every individual post. I wanted to repurpose a tumblr I had been using for feed aggregation and it had over 18,000 posts. That’s a lot of clicks.

Enter the TumblrCleanr. Provide it with your tumblr domain name as well as your username and password and it will delete up to the latest 3000 posts at a time. You can keep running it until your entire tumblr is clean as a whistle.

This script will DELETE ALL POSTS ON YOUR TUMBLR WITH NO BACKUPS. If that isn’t what you want to do then please don’t use it. :)

How to Install the Exception Notifier Plugin with Ruby on Rails

Exception Notifier is a Rails plugin that will email you when an error occurs in your Rails application with full debugging information. It’s as useful as you can imagine, and running it is the difference between happy users and grumpy users who don’t use your web app because every second click looks like this:

Agile Web Development with Rails v2 has the skinny on how to install this plugin starting on pg 629. In my infinite Rails Newbieness, I still had a heck of a time getting it working properly despite excellent guides like this one or the official install notes.

The Newb’s Guide to getting the Exception Notifier plugin to work in Rails

#1: That was easy – Installing the Exception Notifier Plugin

Step #1: On the console in your Rails application root directory type:

 
ruby script/plugin install exception_notification

Step #2: Add the following line to your config/environment.rb file AT THE END OF THE FILE:

 

# Include your application configuration below

ExceptionNotifier.exception_recipients = %w(your@emailaddress.com)

Step #3: Since you’re already changing configuration options, you might as well change these two from the default while you’re at it.

 
ExceptionNotifier.sender_address = %("Application Error" <app.error@myapp.com>)

# defaults to "[ERROR] "

ExceptionNotifier.email_prefix = "[APP] "

Changing the sender_address can go a long way to preventing the emails from being marked as spam.

Step #4: Restart the server! You’ve installed a new plugin which means you have to restart the server in order to use it.

Gotcha #1:

 

active_support/dependencies.rb:266:in `load_missing_constant': uninitialized constant ExceptionNotifier (NameError)

This means that you put the ExceptionNotifier.exception_recipients line in the wrong spot. It goes at the end of the file, not in the class.

#2: The Postman Rings Never – How do I debug the email notification?

Step #1: Open up a console windows and do a tail -f log/development.log and you’ll be able to see the Exception Notifier plugin trying to handle the emails.

It will show information like who the email is being sent to, and delicious tidbits like the email is crashing with an SMTP Authentication Error.

 

endering ./script/../config/../public/500.html (500 Error)

rendering section "request"

rendering section "session"

rendering section "environment"

rendering section "backtrace"

Sent mail:

From: Exception Notifier <exception.notifier@default.com>

To: engtechwp@gmail.com

Subject: [ERROR] mycontroller#error (Net::SMTPAuthenticationError) "334 HASHINFO"

Mime-Version: 1.0

Content-Type: text/plain; charset=utf-8

A Net::SMTPAuthenticationError occurred in mycontroller#error:

#3: But Does It Blend? Generating Exception Notificiations on Development

Step #1: Create a controller action that will always generate an error

Edit one of your controller files and add these lines

 

def error

raise RuntimeError, "Generating an error"

end

You don’t need to create a view for it.

Step #2: Change your development settings to let exceptions generate email notifications. In config/environments/development.rb change these two lines

 

#config.action_controller.consider_all_requests_local = true

config.action_controller.consider_all_requests_local = false # debugging exception_notifier

#config.action_mailer.raise_delivery_errors = false

config.action_mailer.raise_delivery_errors = true # debugging exception_notifier

Step #3: Tell Exception Notifier to ignore it’s local address rules

In app/controllers/application.rb

 

include ExceptionNotifiable

local_addresses.clear # always send email notifications instead of displaying the error

You’ll want to remove these changes once you know the Exception Notification plugin is sending emails.

Step #4: Try it out! Navigate to the http://yourapp/controller/error action you created in step #1 of this section. Instead of seeing the debugging trace you’ll see the standard application error page that your users see. But did you get the email?

#4: The Spice Must Flow – Configuring Action Mailer

If you already have a working ActionMailer configuration then skip this section.

The default settings for Action Mailer will use SMTP on localhost. Give it a try and see if it works. If it doesn’t get sent then it may be because you’ve never configured Action Mailer to know anything about how to send an email! Configuring Action Mailer is  covered on pg 567 of Agile Web Development with Rails v2.

You can see if the email was sent or not by looking at your development log file and seeing if there are any dread SMTP errors like

 
535 5.7.3 Authentication unsuccessful. 

Exchange can be a cruel mistress.

The settings go in config/environment.rb (or one of the files in the environments subdirectory if you have different mail settings for different servers). You’ll have to figure out the correct settings by checking your mail program or by bribing the IT guy.

 
config.action_mailer.delivery_method = :smtp

config.action_mailer.smtp_settings = {

:address => "domain.of.smtp.host.net",

:port => 25,

:domain => "domain.of.sender.net",

:authentication => :login,

:user_name => "user",

:password => "secret"

}

More information about the ActionMailer configuration options.

I’d like to give a big thank you to all of the commenters on this post, without which I wouldn’t have gotten this working.

Yahoo Pipe: Sub-Reddit Feed Filter

Popular social bookmarking site Reddit has announced a great new feature: users can create their own sub-reddit. What does this mean in English? Users and communities can create their own social bookmarking sites around specific topics: blogging, wordpress, specific programming languages, etc but still use their regular reddit account for submitting links and voting.

You can see a full list of all the new reddits here, sorted by popularity. Of particular interest to me is the new Reddit created for Ruby/Rails related posts.

Of course, it’d be nice to be able to subscribe to a filtered version of these links. I’ve created a modified version of Dave S‘s “reddit popular on delicious” Yahoo Pipe that works with Sub-reddits.

http://pipes.yahoo.com/engtech/subredditpopularondelicious

1. Click on the link
2. Enter the name of the sub-reddit you’re interested in
   • ie: ruby, see full list of all the new reddits here
3. Enter the minimum number of saves on a delicious before a link is included in the feed
4. Enter keyword inclusion/exclusion filters if you want to limit what you get
   • ie: include only rails-related posts or exclude all rails-related posts
5. Click Run
6. Click on the subscribe to RSS button

I’m using the Ruby sub-reddit as an example, but this is a great way to track links based around any topic there is a sub-reddit for. Even lolcats.

I’m looking forward to when this Reddit feature comes out of beta and it’s possible to create a few new sub-reddits like blogging, wordpress and lifehacks.

Related Posts

• Greasemonkey Script: Yahoo Pipe Cleaner
• Blog Tip: Create a Link Post in 3 Seconds
• The Programmable Web – Yahoo Pipes

Getting Started with Ruby on Rails – Week 3 – Testing

I’ve fallen for the hype and started using Ruby on Rails for building database driven web applications. You can follow along with my weekly experience discovering gotchas with Ruby on Rails.

Previously: Getting Started With Ruby on Rails – Week 2

(I swear, back to your regularly scheduled non-rails content soon enough)

Gotcha #1 – after_initialized is after_instantiated

Yes, after_initialized is called more often than just when you call Model.new. Use if new_record? inside of it.

Gotcha #2 – button_to has it’s own class

You can’t pass :class parameters to the button_to helper because it creates it’s own :class=>”button_to”. Use :id instead.

Use console

script/console will give you an interactive console for playing with objects. Use it! It makes debugging tiny little gotchas with ruby syntax you might not be familiar with so much easier. Type reload! in the console to reload your models after any changes you’ve made. Type object.methods to see a list of everything an object responds to.

You can use many familiar console navigation keys like Up, Down to move between previous commands and Ctrl-A for start of line and Ctrl-E for end of line.

The Migration Shuffle

When you’re building a new migration on your development database always do the following:

rake db:migrate
rake db:migrate VERSION={current version - 1}
rake db:migrate

It’ll let you know that you’ve made an error in your down method right away, instead of weeks later when you’re trying to rebuild the database.

Little Bobby Tables

At some point your going to write a bad migration and screw up your development database, so rebuild it.

> mysql -u root -p
drop database proj_development; drop database proj_test;
create database proj_development; create database proj_test;
quit

> rake db:test:prepare

> rake db:migrate

http://xkcd.com/327/

Data Migrations

If you’re building data migrations, always uses .save! so that it will fail on a validation error and you may want to litter your migration with puts statements to jump to which object is failing validation. There’s probably a better way of doing this using fixtures, or using –trace to find which migration failed.

Or hell, don’t use a data migration for bulky legacy data.

There’s Something About Tests

I really like how simple it is to write fairly complicated tests. One thing I didn’t like was how many tests it is possible to write. The examples from Agile Web Development with Rails showed them creating a lot of tests for the validates_* helpers. Unfortunately, you don’t need to create tests that duplicate those helpers because they are bulletproof. You do however need tests to prove that you used them correctly.

Cut-and-paste errors do happen, and double checking my validations did reveal at least one case where I thought I was validating a field but I wasn’t. Not to mention that if you’re using a regular expression filter to validate the format of a field you might forget to put start and end delimiters on it. Even testing something simple like all values are in the list is useful because you might have another validation that invalidates one of the values from your list.

Ruby is Dynamic

One thing I can’t stress enough is how much you NEED unit tests. Ruby is a dynamic language, and as such there isn’t a great and easy way to find out if the code will blow up without running it. If you run it by hand you won’t find all the interesting scenarios for the simple reason that you won’t be rechecking features you implemented last week that exploded because of a change you made this morning. You need a regressable test suite.

And there’s nothing like writing a test to make you realize how much more complicated you’ve made things than they need to be.

How to Run Tests

Run an individual test

ruby test/unit/testname.rb

Run multiple tests:

rake test # run all test
rake test:unit # run unit tests
etc

They can all be done inside of emacs by using the Tests drop down menu in rails-mode. This is the preferred method because you can click on errors and go directly to that file.

rails-mode also lets you use C-c C-c . to run the current test file. This allows you to rapidly iterate through test development.

Running Tests – Verbose Assertions

Here’s another tip that I didn’t realize at first: you can supply a message argument to your assertions that will display when it fails. This is essential if your using loops in your tests, IE: looping over an array of invalid field values, because the line number isn’t enough information to find out why the test failed.

Debugging a Test – Breakpoint

You can use the breakpoint keyword where a test is failing. This will open up a console at the breakpoint spot. Unfortunately it doesn’t work well inside of emacs because the ROutput buffer is read only (in fact, you’ll have to kill the process). So run the test from the command line when you want to play with breakpoints. I can’t seem to find a way to access the local variables in a method… so on to ruby-debug.

Debugging a Test – rdebug (or redbug according to Microsoft Word)

sudo gem install rdebug -y

in config/environments/test.rb

require 'ruby-debug'

Then use the debugger keyword instead of the breakpoint keyword where you want to stop. Don’t use it when you’re running tests from emacs because things will look weird.

Running Tests – Fixtures – Validating Fixtures

Here’s the fun bit: sometimes you break your fixtures. Not on purpose, to test bad data, but because your erb goes a little wrong, or because they’ve gotten out of date with your schema. Here’s a rake task that will let you do rake db:fixtures:validate

If you are using erb to generate your fixtures, you can also see how your fixture will roll out using:

erb test/fixtures/fixturename.yml

And while you’re at it, you probably want to validate your existing database against your models. Here’s a rake task that will let you do rake db:validate_models

Running Tests – Advanced – autotest (part of ZenTest)

There’s a plugin called autotest that will automatically run tests on any files that have changed. This is great because you can keep the console open in the background and it will immediately catch if you’ve saved a file with a typo! No need to go to the web browser, navigate to the changed page and hit refresh. In fact, using the web browser should be an afterthought… you should be able to create tests for any features.

sudo gem install ZenTest
rehash
autotest -rails

One gotcha: disable autotest if you’re manually running tests as well! You’ll end up creating duplicate records in the test database. The solution is: don’t manually run tests with rake at the same time as autotest.

Walkthrough of autotest: http://maintainable.com/articles/dry_up_testing_with_autotest

There’s a way to integrate autotest into emacs.

Running Tests – Advanced – RedGreen (for autotest)

Not the horrible Canadian TV show, but a notifier for autotest status reports.

https://wiki.csuchico.edu/confluence/display/webd/Testing+Rails+Apps

Running Tests – Advanced – ZenTest

ZenTest is useful for parsing your rail files and creating stubs of tests.

Running Tests – Advanced – Test::Rails (part of ZenTest)

Test::Rails provides a mechanism for splitting functional tests into controller tests and view tests. This decoupled lets you check your business logic as is, and your view routing as is.

If you want to add a generator for creating view/integration/controller tests:

./script/plugin install http://topfunky.net/svn/plugins/vic_tests

Some collected thoughts about Test::Rails

• Assertion Cheatsheet
• http://www.linuxjournal.com/article/7776
• http://blog.michaeltrier.com/2007/3/17/working-with-test-rails
• http://tuples.us/2007/06/03/fragility-of-view-tests/

Running Tests – Advanced – Rcov

Rcov is another tool that will help your testing by calculating the code coverage of your tests. This is an essential tool to find holes in your testing strategy. All the usual caveats of code coverage apply.

http://eigenclass.org/hiki.rb?rcov

sudo gem install rcov
rehash
rcov test/path_to_specific_test.rb - or - ./script/plugin install http://svn.codahale.com/rails_rcov

Now you can do

rake test:units:rcov

http://agilewebdevelopment.com/plugins/rails_rcov

Running Tests – Advanced – Heckle

Heckle mutates your code to see if the tests actually check anything. Unfortunately highly coupled code is heckle-proof because changing anything breaks everything else.

sudo gem install heckle

Running Tests – Measuring – Flog

Flog measures reports a score based on how complex it thinks your code is. The higher the score, the higher the chance that there is a bug hiding there.

sudo gem install flog

A Handful of Blogs About Rails Testing

These guys have written a lot (all?) of the plugins I’ve mentioned and are worth checking out if this stuff interests you:

• http://blog.zenspider.com/
• http://blog.segment7.net/
• http://nubyonrails.com/articles

Related Posts

• Getting Started With Ruby on Rails – Week 1
• Getting Started With Ruby on Rails – Week 2
• Book Review: Ruby on Rails for Dummies

Getting Started With Ruby on Rails – Week 2

I’ve fallen for the hype and started using Ruby on Rails for building database driven web applications. You can follow along with my weekly experience discovering gotchas with Ruby on Rails.

Previously: Getting Started With Ruby on Rails – Week 1

Emacs Rails-mode

Last week I complained about wasting time setting up rails-mode in emacs. I’m starting to find some real time saver though. The navigation short-cuts are absolutely necessary for navigating the file structure of a Rails application and I really like how the syntax highlighting can capture lines that don’t make any sense to Ruby. This is a great feature if you’re learning Ruby at the same time as you’re learning Rails. It has auto completion for “”, [], {} and ending function blocks and even picks up things like when you have one too many ends in your file.

Which files should be checked in?

I couldn’t find a list of what files are allowed to be checked in anywhere in Agile Web Development with Rails. The answer seems to be anything but:

db/schema.rb # easier to let your db:migrate control it
config/database.yml # because it contains database passwords
coverage/* # generated by rcov
logs/* # generated by server
tmp/* # temporary sessions files

Don’t overwrite the flash

Bad, no validation errors will be shown:

@model.save
flash.now[:notice] = "I saved it"

Better:

if (@model.save) then
flash.now[:notice] = "I saved it"
end

Will trap and display ruby errors as well as validation errors:

begin
if (@model.save) then
flash.now[:notice] = "I saved it"
else
  raise "Error saving"
end
# Do stuff
rescue Exception => e
  flash[:notice] = e.message
end

Keep controllers streamlined

I found myself creating one controller that had add/show/delete/list actions for multiple models. It’s much cleaner to have multiple controllers for the individual models.

Conditional Linking

link_to_if will put an unlinked version of the text if the conditional is false. This is much more useful than removing the link text completely for a lot of situations, because you don’t have to worry that the rest of the text around it will look weird. Don’t try to use html_options as a hash! I lost quite a bit of time to this because it won’t use the method parameter, but it doesn’t give you an error.

link_to_if (check_if_user_can_delete),
	"Delete Image",
	{ :action => "delete", :id => @image.id },
	:confirm => "Are you sure?",
	:class => "dangerous",
	:method => :delete

Generate validates_* off of database

I would have liked it if the generate script automatically generated validates_* helpers off of the database table. validates_length_of could be generated for :limit and validates_numericality_of could be generated for :integer.

Using the same partial to display create/edit/show

This is a neat little trick I found. You can use the same partial for your create/edit/show actions by using html_options and setting

{ :disabled => (controller.action_name == "show" ? true : false) }

for all the fields. It might not be useful for many public applications, but for an internal app it’s a great way to use the same ajaxy displays that you use for create/edit in show.

Polymorphic Associations

Are weird if you want to validate uniqueness. They might work better with has_many relationships than with has_one relationships. Or, I made it more complicated that it had to be.

Deploying sucks

It’s true. Played around a bit with capitrano and vlad the deployer but the both seem to assume you’re using subversion.

Free Tidbit: How crypt works in passwd files

I don’t know why this was so hard to find in Google: passwd files that use the crappy crypt mechanism use the first two characters of the expected password as the salt!

given_password = "hello_world"
encrypted_password = "ahga3sgj"
return encrypted_password == given_password.crypt(encrypted_password.slice(0,2))

and don’t worry, I’ll talk about something other than Rails later this week :)

Book Review: Ruby on Rails for Dummies

I don’t have anything against the for Dummies series (one of my friends is an author), but they’re only good when you want a very general understanding of a concept. I wouldn’t recommend the series for technical books. But my local library happened to have a copy of Ruby on Rails for Dummies, so I gave it a try.Here’s the good news: if you’ve ever used a programming language or used any HTML then you can skip the first 150 pages.

The 26 pages of how to install the software can be skipped by using InstantRails and then downloading RadRails. You’ll want to pay attention to pages 104 to 112 where the author delves into some of the ways Ruby is different than other programming languages (blocks, yielding, symbols, 0 is true).

The book uses RadRails for all of its examples; which is fine except that it takes so much longer to explain how to do something with a GUI than it does to type rails myproject or script/generate controllers ShoppingCart show. I really hate that they don’t show the one line console command as well as the four pages of GUI operations and screenshots. They don’t specifically mention which version of Rails they’re using, but the installation screenshot shows rails-1.1.2, which is a little on the old side (although the only errata I’ve seen is that require_gem doesn’t work anymore).

Thankfully once you’ve skipped ahead to chapter 8 and they start dealing with Rails in all its glory the book gets a lot better.

What The Book Covers

• Stuff to skip
• Chapter 8: view, controller, partials, helpers
• Chapter 9: model, migration
• Chapter 10: linking with image_tag, link_to, h, how ERb rolls out to HTML
• Chapter 11: uploading a file, storing binary data in database
• Chapter 12: validating input, belongs_to/has_many/many-to-many
• Chapter 13: AJAX, sending email, XML, SOAP web service
• Chapter 14: web sites (most are still alive)
• Chapter 15: lots of ruby-specific tricks with no details
• Chapter 16: Rails concepts aka “I have a job interview in 10 minutes!”
• Chapter 17: using Rails on legacy databases

What could be discussed more

• debug helper
• CSS
• RJS
• Layouts
• Testing
• Fixtures
• REST
• Rdoc
• routing

One thing that’s pretty dang neat is that the author provides his email address and his phone number. That’s an impressive level of service. He tries a little too hard to be funny in the book, but there were some parts that made me chuckle (like when he talks about sending email reminders to his wife, but using instant messaging when he needs her urgent attention).

Unfortunately I’d recommend picking up a copy of Agile Web Development with Rails (AWDWR) instead of Ruby on Rails for Dummy (RORFD). RORFD is split into many small unrelated examples while AWDWR has more extensive example code that you could use as a skeleton for a professional site. AWDWR is much clearer to read than RORFD, which always interrupts the flow with a new figure and screenshot. One page of text may cross-reference up to ten other figures/screenshots/chapters. It feels like RORFD has ADD and it doesn’t make for an easily digestible read.

You can find a more favorable review here.

Getting Started With Ruby on Rails – Week 1

I’ve fallen for the hype and started using Ruby on Rails for building a database driven web application. If you’ve never heard of Rails it is a web framework using the Ruby programming language. Ruby is an object-oriented interpreted language, that’s often compared favourably with Smalltalk. [1] What’s a framework? A framework provides a structure and a set of tools usually for solving a particular type of problem. A programming language solves general problems while a framework extends a programming language to better solve a specific problem.

Rails is a framework for building web applications: stuff like blog software, instant messaging, to-do lists, web magazines, and your favorite web comic. Word on the street is that ROR is a resource hog but the resource consumption is balanced out by how much more productive it is to develop with. It’s easier to buy more computers to host a web application than it is to hire more developers. Computers get more powerful over time; developers not so much.

I’ve been developing websites as a hobby off and on since 1994, but I only learned CSS in the past six months. I’ve done some minor hacking of other people’s web apps that were written in ASP or Perl and they were always horrible messes of spaghetti code. I’m really looking forward to trying out a web app from scratch.

Choose Your Path

I run a Windows machine with a VMWare Linux box inside of it, so I can choose to do my Rails development under Windows or under Linux. If I use Windows then I can use InstantRails, which is a one-click installer that gives you everything to need to start coding ASAP. But I much prefer developing under Linux because you can’t beat the power of having a strong command line. The Windows command line console is a joke, and requires a ton of 3rd party utilities for stuff that’s already there under Linux. [2]

The downside is that there is no one-click install for Linux. Well, except for this one, which I didn’t notice until now :)

Installing ruby, gem and rails is simple and I was able to do it under my user account using the standard –prefix=/home/engtech install options.

Gotcha #1 – MySQL

I already had MySQL installed on my Linux box but it was an extremely old version that blew up the second I tried to use Rails to talk to the database. You need at least MySQL 4 to use Rails because it uses ENGINE=InnoDB for its calls. Older versions of MySQL don’t have InnoDB turned on by default, and once you do turn it on they only understand TYPE=InnoDB.

Mysql::Error: You have an error in your SQL syntax near 'ENGINE=InnoDB'

Tip: Get the latest and greatest version of MySQL instead of whatever came with your Linux install. I needed the Server, Client, and Developer RPMs. MySQL was the part of the install process that required root access.

Tip: If you use a password for your MySQL root account, make sure you change config/database.yml to use it.

Gotcha #2 – Integrated Development Environment (IDE)

Rails doesn’t come with a standard IDE, but instead gives you a wide option of choices. Aptana RadRails, based on Eclipse is a good choice. But I’ve already sold my soul to one editor for all my coding needs: emacs. Emacs is the “kitchen sink” IDE because it supports everything: you can find extensions for any programming language or task. The downside is that it has a learning curve like you wouldn’t believe.

There’s a tutorial on how to add rails support to emacs. It’s long and complicated. Using rails mode in emacs requires upgrading to emacs version 22 that broke a lot of my existing DotEmacs hacks. I eventually got it working, but in retrospect I might have been better off going with RadRails because I lost hours to this. I’m still finding emacs keystrokes that don’t do what I expected them to.

I’m unimpressed that there isn’t a quick reference print sheet for rails-mode, this is the best that I could find. So far I’ve only been using the syntax highlighting and C-c C-c g K and C-c Up / C-c Down to navigate between files.

Gotcha #3 – Development Server vs Production

When I was running into MySQL installation problems, I toyed with using SQLite3 instead for a while. Needless to say, make sure your development database is using the same versions of everything as your development and test servers. It’ll save you lots of headaches.

Initial Opinion

People weren’t lying about how productive programming with Ruby on Rails is. In the same amount of time it took me to write this blog post I was able to get a simple web application with user authentication up and running with a web interface that is probably “good enough” for final release. Which is ridiculous, compared to my previous experience hacking apps together using ASP or Perl.

• Directory structure – Clean, clear, and everything has it’s place.
• Naming conventions – One of the best things a framework can give is enforcing a standard way of naming things. It takes a while to learn it, but it becomes second nature that if a class is called X, the database table is called Y and the tests are called Z. If you leave it to themselves most developers create small inconsistencies in naming conventions that waste time — especially if more than one person is working on the code.
• Don’t Repeat Yourself – I really like the way Model/View/Controller separates the code and keeps it becoming a mess. Inheritance and helpers/partials are great for keeping you from duplicating code.
• Succinct – Wow, you really do get a lot done with very little code writing. They weren’t kidding when they said you could write blogging software in under 15 minutes.
• HTML / CSS / XML – I really love that it doesn’t try to hide the HTML, CSS and XML under a lot of programming calls. There are helpers for doing common things, but you’re free to write your own web code.
• Development / Test / Production – In my limited experience with web apps, I’ve never worked on anything that had more than 20 users. Testing was all done manually, and the production server was the development server. It was a mess. Clean separation makes it much easier to work on code independently and only push it out to users once it has been rigorously tested.
• Migrations – We use to build our database tables using a PHPMyAdmin web interfaces. Needless to say, doing it through scripting where you can tear down, reassemble, and rebuild the database tables is much cleaner because everything is reproducible from scratch.
• Rake, rdoc, and test – One of the things I like most about Ruby is that it has all the fixings I expect from modern languages: the ability to automatically generate documentation off of the code and a built-in unit testing and build framework. I’m always amazed when I see a language that doesn’t natively support these facilities.
• Religion – The big downside to Ruby on Rails is that it feels a little bit like a religion sometimes.

Conclusion

I should have tried Ruby on Rails a long time ago. I spent entirely too much time setting up my development environment compared to when I could have been developing a web application. I could have been up and running in less than an hour if I had:

1. Used InstantRails
2. Used Aptana RadRails

Footnotes

1 – Did you know that Smalltalk inspired the Macintosh GUI? Smallpark was yet another example of the magic that was going on at XEROX PARC in the 70s. These are the guys who invented the mouse, colour graphic, windows/icons for a GUI, WYSIWYG text editors, Ethernet (how you talk to other computers on a network), and laser printers. Programmers at Work featured interviews with some of the people from PARC.

2 – I’m always amazed that people can program without easy access to diff, find, grep, perl, etc. All of these things are available for Windows for free, but they never work quite the way I expect them to.