Ruby Style Guide -- Modified version from y8/rails.textile and converted to Markdown (GFM)

rails-guide.md

Ruby on Rails Coding Style Guide

This guide is more or less what my views on the "do's and don't's" of Ruby on Rails. As the word "guide" implies, it's only meant as a guideline and can be modified. There are some things that it is more important to agree as a team what the standard should be, and not just impose one (such as spaces vs tabs).

Code style

• Use UTF-8.
• Use 2 space indent, not tabs.
• Use Unix-style line endings.
• Keep lines no longer than 120 chars for code, 80 chars for documentation.
• Remove trailing whitespace.
• New line at end of file.

Development process

• Think
• Describe
• Write tests
• Implement & go green
• Rethink
• Refactor

MVC

• Follow MVC conventions
• Follow "Fat model, skinny controllers" methodology
• If you have different data representation, use format aliases (e.g. different html views for same data: /users/:id.pdf)

Controllers

• Keep it simple and clean
• Keep ApplicationController clean. Limit use to global filters and per-request logic.
• Keep in mind that all ApplicationController filters will be executed in each request, so optimize it to be efficient.
• Keep skinny controllers. Controller logic should be simple and straightforward. Heavy lifting should be done in models. E.g:

  # Bad Practice
  Account.transaction do
    transfer = @sender.orders.new(:action => :transfer, :receiver => @receiver, :ammount)
    
    if @sender.assets >= amount
      @sender.assets -= amount
      @receiver.assets += amount
    else
      flash[:error] = "Balance not enough to transfer funds"
      success = false
    end
    
    if @sender.save! and @receiver.save! and transfer.save!
      flash[:info] = "You have transferred #{ammount} to #{@receiver.last_name + "" + @receiver.first_name}"
      success = true
    else
      errors = ...
    end
  end
  
  if !success
    respond_to ...
  else
    respond_to ...
  end

  # Better
  Account.transaction do
    @sender.withdraw amount
    @receiver.deposit amount
  end

  if @sender.errors? or @receiver.errors?
    respond_to ...
  else
    respond_to ...
  end

  # Best
  if @sender.transfer!(amount, :to => @receiver)
    respond_to ...
  else
    respond_to 
  end

• Place view interactions in respond_to blocks.
• respond_to blocks should be logic free.
• Avoid deep nesting, unless absolutely necessary.

Models

• Keep it simple and clean
• Model, method and variable names should be obvious
• Do not use shortcuts and avoid non widely used abbreviation for model names. (e.g UsrHst or UserHist should be UserHistory)
• Follow the DRY principle, but don't overdry.
• Scope similar or same condition logic.
• Modular-ise when there are repeated sections of code.

Views

• Presentation only in views.
• Any presentation logic should be used within a presenter.
• Any presentation or complex view logic that is limited in quantity should removed from the view and placed within a helper or presenter.
• DRY. Use partials, but keep in mind that partials can be really slow
• Keep content separated from presentation.
• Avoid inline scripts.

Tests

• Follow Test Driven Development methodology: write tests, then code
• Keep tests simple and easy to understand.
• Test everything what should be tested. If something can be broken: try to break it through tests.
• Test what you write; don't try to test built in methods.

Comments and documentation

• Respect other developers.Provide English documentation, even if not primary language.
• Let code be as self documenting as possible, but always include comments and documentation for complex or highly specific areas. E.G. If there is a "magic" number, document why it is necessary; don't just let it hang out for a future developer to question it without an answer.
• Lean toward more, vs less, when documenting, but try not to overdoc or document the obvious.