Ruby (Rails) Best Practices (Part I)

Hello, Friend

This guide opines on how to write readable and maintainable ruby code. Ruby offers a few good ways to perform any task and several notably bad ways. For common situations, this guide puts forth a default option. If you and readers of your code follow those defaults, you will disagree fewer times on matters of style and receive swift reviews. There are times when these defaults will not be appropriate. To that:

It is an old observation that the best writers sometimes disregard the rules of rhetoric. When they do so, however, the reader will usually find in the sentence some compensating merit, attained at the cost of the violation. Unless [you are] certain of doing as well, [you] will probably do best to follow the rules.¹

This applies as well to writing code as it does to writing English. Break the rules only when you have adequate rationale.

Readability, In General

As a rule, your code will be read more often than it is amended. Your readers may be junior, they may be from other teams, and, in almost all cases, they will be unfamiliar with your intent. As a software engineer - as opposed to a hobbyist programmer - it is a primary function of your job to write code that can be maintained. Readable code is a necessary (if insufficient) prerequisite to maintainable code.

While an imprecise target, readable code possesses these attributes, which are used to organize the remainder of this guide.

• The code has clear intent. It does what it intends
• The amount of context the reader must keep in mind is minimal
• The code is written as legibly as possible
• The code be written in the simplest way, up until it is necessary that it is not.²

Breaking the KISS principle is the most common way very smart programmers write unmaintainable code.³

Frequently, the KISS principle will be violated by

• Optimization
• Metaprogramming
• Design Patterns (looking at you, pub/sub)
• Application of the “Don’t Repeat Yourself” (DRY) principle

All of these things are useful tools and should be used when simple code cannot reasonably do what it needs to. They should be used sparingly. Typically there comes a recognizable tipping point for when they become necessary.

Many of the tactics in this guide encourage you to use restraint when using all the clever things your computer science degree or Design Patterns taught you. I enjoy design patterns. Most of the time, they obfuscate the code’s purpose.⁴

Chapter 1: Good code has clear intent. It does what it intends

1.1 Naming - General

Good names are expressive and concise. Names ought to be as specific as necessary for the context but not more. Good names avoid jargon when possible, especially programming jargon. Business domain jargon is acceptable, when needed.

1.2 Naming - Objects

Objects (classes, generally) are. Consequently, name objects with nouns. There’s a huge corollary here that you may need not make an object if your intent is to execute an action rather than to represent a thing.⁵

1.3 Naming - Functions and Methods

Functions do. Consequently, name functions with verbs. Expressivity is key to function names. “Perform”, “Run”, “Execute”, and “Do” are useless names except in the context of a job or service object. Even then, consider if instance or static methods might do better.

# Poor
class WidgetSpinner
  def perform
  end
end

# Better
class WidgetSpinner
  def spin_widget
  end
end

class SpinWidgetJob
  def execute
  end
end

# Best
class Widget
  def spin
  end
end

When choosing what verb to use, try to be precise and consistent. Consider the common example of a method on an ActiveRecord model that retrieves some information from a model or service object built around a database table. ‘Get’ may be sufficient, but there are a lot of operations that do more than just ‘get’. In these situations with common operations, try to develop a precise nomenclature and apply it uniformly. In this case, I suggest:

• Get - the datum exists. We are merely retrieving it.
• Build - the datum does not exist. We are creating the datum but not persisting it.
• Assemble - the datum does not exist. We are putting together other data to return it. We are not persisting it.
• Calculate - the datum does not exist. We are running some computation (eg. a sum) to return it. We are not persisting it.
• Create - the datum does not exist. We are creating the datum and persisting it

When naming a method, assume the method will succeed. For example, even if manipulating inventory data may throw a database locking error set_onhand_quantity is a better name than attempt_to_set_onhand_quantity. If a method can throw an error in normal use, those errors should be anticipated, documented, and handled by the client code according to the use case (see Errors & Return Types, Doc Blocks).

1.4 Naming - Variables

Variables are especially context sensitive. When you are writing a simple method, you can often get away with using the type as a proxy for the identity of a variable. The following examples are clear in that they express both identity and type.

unicorn = Unicorn.first # A single variable, named for its type
unicorns = Unicorns.all # A simple enumerable comprised of a type

# A hash, named by its type
unicorns_by_horn_pattern = {
  Unicorn.first.horn_pattern => Unicorn.first,
  Unicorn.second.horn_pattern => Unicorn.second,
} 

Type becomes an insufficient proxy for identity once more than one variable of a type enters the same context. In this case, we need to be more specific. Our objective now is to obviously distinguish between variables of the same type.

sparkly_unicorns = Unicorns.sparkly.all
shiny_unicorns = Unicorns.shiny.all

As seen in these examples, it’s helpful to also observe these hard rules:

• Enumerables should use a plural name
• Hashes should follow the pattern <value>s_by_<key>

1.5 Raise Errors

When using a method, we should be allowed to assume it will succeed. To guarentee this assumption, a method must raise an error on failure. A method that both fails to complete it’s objective and does so without complaint is nearly impossible to design around.

Being clever, for example returning nil rather than the expected type, results in unpredictable behavior. Often the nil will pass back through the execution stack some way before the code attempts to use it and raises an error. At that point, the error diagnosis becomes a forensic expedition. A clear cut error at the moment of failure saves us from this.

Instead:

1. Aim to fail early with as much explanation as context allows. Typically, the place to start is with a custom error.
2. Document the errors that are expected either in the immediate method or those in client methods that will be unhandled.
3. Then, at the level at which it makes most sense, catch those errors and handle them.
4. Do not suppress errors! Suppressing errors is extemely counterproductive because your code will not only fail but give you no clues for diagnosis.

Let us see what these tips look like in action.⁶

class Flamingo
  MIN_HEIGHT = 50 # cm

  # Define a simple custom error class 
  # The unique name alone is quite helpful for us to catch errors
  # and deal with them accordingly.
  class FlamingoNotFoundError < StandardError; end

  # Define a more nuanced custom error class
  # This can be used to capture relevant context that can be
  # extracted and used by error handling code
  class TooShortError < StandardError
    def initialize(name, height)
      # So callers can eg. tell the user which flamingos are too short
      @name = name 
      @height = height 
      @min_height = MIN_HEIGHT

      super("Proposed flamingo height of #{height} is too short.")
    end
  end

  #  
  # @param flamingo_name [String]
  # @param new_height [Numeric]
  #
  # @raise [Flamingo::TooShortError] If the given height is too short
  # @raise [Flamingo::NotFoundError] If the name does not match 
  #   any existing flamingos
  # 
  def self.update_height(flamingo_name, new_height)
    if flamingo.new_height < 0
      raise Flamingo::TooShortError.new(flamingo_name, new_height)
    end

    flamingo = Flamingo.find_by(name: flamingo_name)

    if flamingo.nil?
      raise Flamingo::NotFoundError.new
    end

    flamingo.update(height: new_height)
  end

end

...

# One of our client methods
# We are easily and accurately able to give the user pertinent
# information because of our (nicely documented) custom error classes
class FlamingoController < ApplicationController
  def update
    begin
      Flamingo.update_height(params[:name], params[:height])
      flash[:success] = "Flamingo height updated."
    rescue Flamingo::NotFoundError => e
      flash[:alert] = "No flamingo could be found with that name."
    rescue Flamingo::TooShortError => e
      # Use one of the fields we stored away in our custom error
      flash[:alert] = (
        "Flamingos must be at least #{e.min_height} cm tall."
      )
    end
    
    redirect_to :back
    return
  end
end

1.6 Doc Blocks

Ruby is weakly typed for flexibility, not to advantage laziness. You should know the appropriate types for inputs, outputs, and expected exceptions from your function and communicate them to future readers of the code. We capture this information through YARD formatted doc-blocks.

Here are the YARD-doc docs, but I find it’s easier to start with this cheatsheet of examples. In addition to the basic formatting of YARD, I’ve found it’s best to apply these rules in Pillpack code, even where they deviate from the original YARD standard.

• Document all parameters and returns and their types.
• Document parameters, return types, etc in @<tag> <name> [<type>] <desc> order. This clearly delineates the name from the description. Ex: @param best_ferrets [Array<Ferret>] a list denoting the specific ferrets to which this method will dispense treats
• Use |-delimited types or a superclass to describe all types that are expected for parameters or returns in polymorphic functions. Ex: If a function can return integers or strings, [Integer|String] is the appropriate type.
• For a parameter that takes integers, decimals, floats, etc, use [Numeric].

• For a parameter that returns the result of an ActiveRecord where method on the Narwhal model [ActiveRecord::Relation]

• Document nil returns! Otherwise, you are setting callers up for NoMethodErrors. Ex. The return signature for a method that ran find_by on the Tomcat model would be written as @return [Tomcat|Nil]
• Document nils as [Nil] and True/False as [Boolean]. Technically a nil is of the NilClass type and the latter are TrueClass and FalseClass respectively, but it’s common, easier, and equally descriptive to use [Nil] and [Boolean].
• Include function side effects in the general description.
• Include information about any state that must be preconfigured for the function to succeed in the general description, chiefly instance variables or model state.
• Include exception types from functions that your function calls if it will bubble up through your function (ie. is unhandled by your function).
• Document expected exceptions, their types, and their causes.

• Describe all the expected keys within hash parameters where it is realistically possible to do so.

# @param bean_config [Hash] the configuration for a new jelly bean
#   @option :length [Decimal] in millimeters
#   @option :color [Array<Integer>] a 3-element array with ordered
#     RGB values

• Include examples in doc blocks if your function call needs precise configurations, requires hash parameters, uses other unusual types of parameters, or introduces some type of metaprogramming to the caller.

• Respect the 80 character soft wrap and 100 character hard wrap when writing doc blocks. Newline appropriately. It’s typical for the description to wrap multiple times or even start on a new line for long type signatures.

• Document argument names and defaults as follows. This informs the caller both of the default values (if any) and the syntax with which they need to invoke the function.

## Required positional parameters
# ...
# @param bar [String] …
# ...
def foo(bar) 

## Optional positional parameters
# ...
# @param bar="baz" [String] …
# ...
def foo(bar="baz")

## Required keyword parameters
# ...
# @param bar: [String] …
# ...
def foo(bar:)

## Optional keyword parameters
# ...
# @param bar: "baz" [String] …
# ...
def foo(bar: "baz")`

• Omit descriptions of how a function is currently used in client code or, generally, how you intend callers to use your function. Doing so is a form of soft implicit coupling. When that client code is changed, the author must amend your now-inaccurate doc block. Inevitably they will not.

• Omit parameter descriptions where the parameter name is self-explanatory.

Ex: (BAD) @param puppy_description [String] A description of the puppy.
Ex: (BETTER) @param puppy_description [String]

• Don’t write a general description for pure functions in which the function name, the parameter descriptions, and the return descriptions adequately describe the behavior of the function.

# BAD - describes how a function is used in client code
# This method is for used in the XYZ class for the ABC use case.

class Food
  ## BAD - Unnecessary explanation because the functions' purpose
  # and the meaning of the parameters is self-explanatory from name
  # A method that returns whether or not the food is edible 
  #
  # @return [Boolean] Whether or not the food is edible
  def edible?
    … (a one or two line implementation)
  end

  ## BETTER
  # @return [Boolean]
  def edible?
    .. (a one or two line implementation)
  end
end

• Exclude the @return tag in the doc block for void methods.

1.7 Comments

Ruby is quite expressive. Your code itself should clearly explain what it does. If it does not, refactor your code for clarity. If you must leave a comment to explain your shorthand, write your code longform instead.

Use comments, instead, to explain why it does something in four primary situations: - Explanation of requirements - Workarounds for subtle issues - Using common tools in uncommon ways (eg. puts # new line) - Deviations from the ordinary way of doing things (eg. for performance optimization)

Do not comment unnecessarily. Extra comments lull the reader into ignoring useful ones. For example, I often see:

# Iterate through medications to update them
self.medications.each do |med|
  med.update(...)
end

I too can read code. However, if you aren’t sure of a comment’s value, err towards leaving it in.