RoR programming style guide?

Is there a style guide for RoR? For example, I see that rails likes to create things like

<% ... %> <% ... %> <% ... %>

and I'm tempted to write this as <% ... ... ... %>

but I'm not sure if doing so will make my code "look wrong".

Since I'm a beginner, I'd like to get into the habit of writing code that has a conventional look. Years of C coding have convinced me that divergent writing styles [e.g. KR versus GNU] can slow the transfer of ideas. And I know that Ruby has this idea of "beauty". What I'm wondering is whether someone has written some examples of beautiful, and ugly, RoR code.

Google for "style guide". See how many there are for just the English language! Look to see the controversy there was over C and other languages!

"Good practice" is usually "sensible" - as sites like http://webstyleguide.com/ http://www.w3.org/Provider/Style/ http://labs.silverorange.com/local/solabs/include/styleguide/ point out.

Some languages have syntactic necessities (e.g. in C statements end with a semicolon), and that HAS to be respected.

Apart from that, readability and clarity is what counts. Not some prescriptive, and probably anal retentive, set of rules.

You might, for example, look at the HTTP behind many site (try 'view source' on your browser. You will see many "machine generated" pages that would be impossible to debug and many that are quite readable. Personally I think you can learn as much from studying the bad as well as the good.

I'm sure many people will give you detailed rules, but here are mine:

   1. Is it readable and understandable?    2. Does it follow the correct syntax?    3. Does it produce the desired result?       If it doesn't, is the output able to be 'debugged' to determine       the problem?    4. Is it maintainable when you come back to work on it 3 years later?

If you think about it, that applies to any language, templating system or web site.

dankelley said the following on 02/11/2007 07:27 AM:

Hi --

Is there a style guide for RoR? For example, I see that rails likes to create things like

<% ... %>

and I'm tempted to write this as <% ... %>

but I'm not sure if doing so will make my code "look wrong".

Since I'm a beginner, I'd like to get into the habit of writing code that has a conventional look. Years of C coding have convinced me that divergent writing styles [e.g. KR versus GNU] can slow the transfer of ideas. And I know that Ruby has this idea of "beauty". What I'm wondering is whether someone has written some examples of beautiful, and ugly, RoR code.

You can get a good sense of traditional Ruby style from looking at the standard libraries. If you do two-space indenting, under_score names for methods and local variables, ThisStyle for classes and modules, and don't put a lot of spaces around arguments (do(this) but don't do( this )), you'll be well on your way.

In ERb, which the RHTML files use, some new questions come up, because of the templating. I think it's good style to keep HTML out of the delimited code. In other words, do this:

   <% if x %>      <p>Hello.</p>    <% end %>

rather than this:

   <%= "<p>Hello.</p>" if x %>

I also tend to start a new delimiter for an extended clause, like a loop -- in other words, this:

   <% i = 0 %>    <% @things.each do |thing| %>      ...    <% end %>

rather than:

   <% i = 0       @things.each do |thing| %>      ...    <% end %>

Doing it the first way makes it easier to move a loop around, or decide to put something before or after it.

I don't know whether this all adds up to a rule (one statement per delimited clause?), but it seems to cover a lot of the cases I encounter.

David

dankelley wrote:

Is there a style guide for RoR? For example, I see that rails likes to create things like

<% ... %>

That is probably an artifact of a generator. In general, one Rails style guideline is: Don't Lean on Generators. The point of Rails is to write very minimal code into the terminals of event handlers.

and I'm tempted to write this as <% ... %>

Write it like that. However, I'm tempted to write it like this:

<%=    x = Builder::XmlMarkup.new    x.html do       x.body do         x.etc       end    end %>

Sometimes I write whole stretches of HTML not in ERb, but in Ruby as an XmlMarkup. Sometimes that makes it easier to refactor.

Since I'm a beginner, I'd like to get into the habit of writing code that has a conventional look. Years of C coding have convinced me that divergent writing styles [e.g. KR versus GNU] can slow the transfer of ideas. And I know that Ruby has this idea of "beauty". What I'm wondering is whether someone has written some examples of beautiful, and ugly, RoR code.

If you have a team, follow what the team does. That fixes the "K&R vs GNU" nonsense. All code should look like only one (very smart) person wrote it. Its technical and esthetic style should be seamless.

Your code should...

- follow team guidelines - pass all tests (and have tests for every detail) - be clear and expressive - obey Don't Repeat Yourself

Under Don't Repeat Yourself, that <% %><% %><% %> sample you posted is not very DRY, because it repeats those silly delimiters!

Ruby, and especially the Rails Inflector, add a new twist to the "clear and expressive" part. We use underscore_identifiers, not camelCase, despite the former is slightly harder to type. We do it because the _ looks as close as possible to a space.

Well formed Ruby statements should read like normal English.

Consider 'Order.has_many :line_items'. That Ruby is so clearly English that it expresses a program requirement. Even a client could read it (if not write it).