Next week marks the publication of the 50th Anniversary edition of the Strunk & White's The Elements of Style, a critically important work for anybody who puts words together on a regular basis.
In that spirit, here are some thoughts on good Ruby & Rails style -- I'm mostly focusing on Ruby-specific guidelines here. This is somewhat closer to a brain dump than a fully-baked style guide, so it's something I intend to come back to, especially after hearing everybody tell me exactly where I'm wrong, wrong, wrong.
UPDATE: There were some comments about the formatting being messed up. Apparently whatever tool we're using for code coloring doesn't work well with Safari. In Firefox, the formatting is as intended. We've cleaned this up -- thanks for your patience.
The goals of well-styled code are correctness and simplicity, in that order.
I don't want to pretend that it's not important for code to be correct. Still, I think that functionally correct code is not the last step. For me, the best order is: Make it Work, Make it Clean, Make it Fast (if necessary).
Ruby code should be indented two spaces.
This should be uncontroversial, right? Indenting Ruby code four spaces indicates that you are a very recent convert from Java.
Statements that extend past 80 characters or so should be broken up and indented on the following line.
This one may be a little idiosyncratic, since I tend to use a narrower edit window than a lot of people. That said, it's still a good idea to have a hard right margin to your code. Whether it's 80 or 100 characters is less relevant than that all of the code can fit on the screen without scrolling. If you have to scroll to see code, eventually, you'll make mistakes based on code that you can't all see at once. (I find this especially true in HTML/ERb, where you can easily mangle a closing tag in column 125 and lose your mind trying to find the problem).
In either case, you should never break up individual sub statements -- in the above examples, never split up a + b -- you should try to keep entire expression, hash or array arguments on the same line even if that means the line above is shorter.
Anyway, both choices have tradeoffs. The double-indent is the easiest to maintain as the code changes, but can make it tricky to follow the logical structure of the code. The longer indent makes it generally clear what goes together, but it's a little hard to keep up, and can look kind of ragged.
I tend to prefer the first form for Ruby, although I do use the second sometimes, especially for, say, hash options inside a larger statement.
Ruby allows you to leave out parenthesis, in general, resist this temptation.
Parenthesis make the code easier to follow. General Ruby style is to use them, except in the following cases:
- Always leave out empty parentheses
- The parentheses can be left out of a single command that is surrounded by ERb delimiters -- the ERb markers make sure the code is still readable
- A line that is a single command and a single simple argument can be written without the parenthesis. Personally, I find that I do this less and less, but it's still perfectly readable. I tend not to like single lines in regular ruby code that have multiple arguments and no parentheses.
- A lot of Ruby-based Domain Specific Languages (such as Rake) don't use parenthesis to preserve a more natural language feel to their statements.
