10 Rules of Thumb to radically improve your Ruby on Rails code

Ruby on Rails has generated a lot of hype over the last couple of years.

This is a good thing - Rails is well-supported and well-understood.

But it's also a bad thing.

Lots of people read the "Agile Web Development" book and then charge a fortune to develop RoR applications. Badly.

I have seen some shocking projects, chock full of the type of spaghetti code that the Rails hype claims you cannot produce (of course this is nonsense - you can write shite in any language).

Over the years I have developed a whole number of "rules of thumb" that I use to evaluate a project's code. These are subjective, inaccurate and open to interpretation. But taken as a whole they give you a pretty decent idea of the state of the code.

And here they are:

rake stats

Look at the ratio of code to tests.

• More code than tests? Lose 10 points
• Between 1:1 and 1:1.5? No points
• Above 1:1.5? Gain 5 points

This test is pretty arbitrary. Just because you have lots of test code doesn't mean that the tests are any good. But not having lots of tests is bad.

Dependencies

Is Rails and any required plugins installed into the vendor folder?

• No? Lose 10 points
• Yes? No points

It's incredibly easy to include the correct version of Rails and all your dependencies within your application tree. Making it easier to share your code with the rest of your team and taking uncertainty out of deployment.

rcov

Is rcov pre-installed?

• Yes? Gain 5 points

rcov is easy to install and pretty useful.

What is the test coverage?

• rcov won't work? Why not? Lose 10 points
• More than 10% red? Lose 20 points
• Less than 10% red? Lose 10 points
• All green? Gain 10 points

This test is also pretty arbitrary. A green line, as above, doesn't mean that the test is any good. But a red line is always bad.

Migrations

Can the database be built completely from migrations?

• Yes? Gain 10 points
• No? Why not? Lose 10 points

Databases are key to Rails development and migrations make them easy to share with your team and deploy to your server.

Logic in all the right places?

Is there any application logic in the controllers?

• Yes? Lose 10 points
• No? Gain 10 points

Controllers are part of the user-interface, function specific and relatively difficult to reuse. Application logic belongs in the models where it can be accessed via the console, not just the web-server.

Is there any application logic in the views?

• Yes? Lose 10 points
• No? Gain 5 points

Views are strictly user interface components - they should be primed by the controller so that the view has nearly all of its decisions made for it.

Warnings and Deprecations

Are there any deprecation notices when running the tests or application?

• Yes? Lose 5 points

Deprecation warnings mean that your code will probably stop working when you upgrade your version of Rails.

Are there any warnings when running the tests or application?

• Yes? Lose 20 points

Warnings are there for a reason. Pay attention to them - in most cases, it is purely laziness that keeps them there.

RDoc

Do all the models have RDoc comments - a header describing the class and comments for each method?

• Header comments? Gain 10 points
• All method comments? Gain 10 points
• Some method comments? Gain 5 points
• No? Lose 10 points

Do all the controllers have RDoc header comments describing their purpose?

• Yes? Gain 5 points
• No? Lose 5 points

Do all the helper methods have RDoc method comments describing their purpose?

• Yes? Gain 10 points
• No? Lose 10 points

Ruby is easy to read and generally pretty easy to understand. That deals with explaining what your code does. But the point of the RDoc comments is to explain why it does it that way, which, arguably, is even more important.

Repeated Code

Is there any repeated code? Are there similar pieces of code in multiple places that could be consolidated into a single parametrised method?

• Yes? Lose 10 points

When writing code if you find yourself writing something similar to code you have already written then it is always worth moving it into a centralised method or class - either as a helper, a model or even a module.

Readability

How readable is the code? Can you tell, at a glance, what the most complicated pieces of code do?

• No? Lose 20 points
• Yes? Gain 20 points

Unfortunately this one is pretty subjective. But, to my mind, code should read like English wherever possible. This may be sub-optimal - especially with regards to performance. It doesn't matter. You can go back, profile the code and optimise the slow bits (of course, your tests make sure that you aren't breaking any functionality). And when you optimise, keep the original (slow) code as a comment to explain what your unreadable (fast) code is doing.

Idioms

Does the code use symbols as hash keys and (the equivalent of) enumerations?

• Yes? Gain 10 points
• No? Lose 10 points

Symbols are sort of like strings but are treated specially by the interpreter - sort of like a literal. Carefully used, they can also make your code more readable.

Does the code pass objects to generate links?

• Yes? Gain 5 points
• No? Lose 5 points

HTTP is not object-orientated but Rails can at least pretend that it is.

Writing this stuff down is strange. It takes things that often comes to me as a "gut feel" and documents and codifies it. Necessarily this means that there are things that I notice that I haven't written down here. Apologies - I will update the article as and when I think of them.

What use is this check-list?

If you are worried about the state of your Rails project 3hv is planning a service where your code is evaluated against these criteria and you receive a detailed report with recommendations for improvement. Excellent for managers who are worried about progress, even better for developers just starting out on Rails. Details are still being finalised but contact me if you are interested.