In this post, I’ll show you a technique I use frequently when refactoring Ruby projects. Let’s take a look at a method I ran across recently that had a very poor quality score.

The Problem Method

This particular project is an e-commerce application that uses a rule engine-like way to perform actions based on a set of rules defined by the store owner. The method below returns a String describing what the rule does in plain English. I’ve shorten this example for brevity, but you can clearly see it’s a mess.

# app/models/rule.rb

def build_message
  message = ["When"]
  case self.subject
   when 'shopping_cart'
     if target == 'sum'
       message << "the Cart subtotal value"
     elsif target == 'count'
       message << "the Cart items count"
     end
   when 'inventory'
     message <<  "Stock level"
   when 'product'
     message << "<i>#{product.to_sentence}</i> page"
   else
     message << values.join(', ')
  end

  case self.comparison
   when '>='
     message << "is greater than"
   when '<='
     message << "is less than"
   else
    message << "is equal to"
  end

  message << values.join(',')
  message.join(' ')
end

rule.build_message #=> "When Cart value is greater than 10"

When we want the rule in plain English, we call rule.build_message and get “When Cart value is greater than 10”. After running Flog and Reek, we get two violations right away.

The “TooManyStatements” metric indicates when a method contains an excessive number of statements, suggesting that it might be performing too many responsibilities. This can lead to increased complexity, reduced readability, and difficulties in maintaining and testing the code.

The “VeryHighComplexity” issue highlighted by Reek points to methods with excessively high cyclomatic complexity. Cyclomatic complexity measures the number of independent paths through a method, indicating how difficult it is to understand, test, and maintain.

The Solution: Builder Pattern (by another name)?

To be honest, I don’t know if we can technically file this under any of the major design patterns, but it’s similar to the Builder Pattern in which we’re creating a separate class for building complex objects. In this case we’re building Strings, which are objects in Ruby so it kind of fits.

We’re going to create a new class for the purpose of constructing our message string. We’re inheriting our new class from the Builder class which will contain shared helper methods we can take advantage of.

# app/builders/rule_message.rb

class Builders::RuleMessage < Builder
  attr_accessor :rule

  def initialize(rule=rule)
    @rule = rule
  end

  def message
    message = ["When"]
    build_subject(message)
    build_target(message)
    build_operators(message)
    build_variables(message)
    message.join(' ')
  end

  private

  def build_subject(message)
    build_shopping_cart(message)
    build_inventory(message)
    build_product(message)
  end

  def build_shopping_cart(message)
    return unless @rule.subject == 'shopping_cart'
    message << "Cart"
  end

  def build_inventory(message)
    return unless @rule.subject == 'inventory'
    message << "Stock level"
  end

  def build_product(message)
    return unless @rule.subject == 'product'
    message << "Product"
  end

  def build_target(message)
    case message.target
    when 'sum'
      message << 'subtotal value'
    when 'count'
      message << 'item count'
    end
    message
  end

  # Translates operators i.e. >= to "Greater than or equal to"
  def build_operators(message)
    message << translate_operator(message.operator) # Helper method from parent Class
  end

  def build_variables(message)
    message << @rule.values.join(' or ')
  end
end

As you can see, our Builder class is much more clean and straightforward. It defines an abstract interface for creating the parts of the complex string e.g. message. It solves both ‘TooManyStatements’ and ‘VeryHighComplexity’ violation by:

1. Separation of concerns: The Builder class separates the construction logic from the object’s class, Rule in our case, allowing for greater flexibility and maintainability.

2. Improved readability: The pattern makes the construction code more readable by encapsulating the construction steps within our dedicated Builder class.

3. Simplified message creation: Our Builder class provides a clear and structured way to create complex strings with various scenarios, making the code more robust and easier to extend.

Let’s see our new Builder class in action:

class Rule < ApplicationModel
  ...
  def to_s
    Builders::RuleMessage.new(rule: self).message
  end
end

Here, we’re overriding the to_s method to display the String version of the Rule object. I don’t always do this, but in this case I think it fits nicely since it is a String representation of the Rule model.

rule = Rule.active.last

rule.to_s #=>  "When Cart subtotal value is greater than 10"

Overall, this technique simplifies construction of building strings in a step-by-step manner while keeping the creation logic separate and providing flexibility. Whenever I encounter a complex method that:

1. Has long lines of code.
2. Uses a lot of if / else statements
3. Is hard to follow or read

I highly recommend employing this technique to streamline the code and enhance its quality. I have extensively utilized this pattern over the years, and it proves immensely valuable when revisiting the codebase after an extended period. By adopting this approach, it becomes significantly easier to comprehend the code’s functionality and seamlessly incorporate enhancements for future features. This practice fosters maintainability and ensures a smoother development experience in the long run. Future Rubyists will thank you 😀.

Let’s take a look at an example I’ve recently came across. I’ve simplified the example for the purposes of brevity, but the idea is the same. This particular project is using a dashboard view displaying recent sales data and comparing results from previous months.

# app/controllers/dashboard_controller.rb

def index
  @current_sales = Orders.where(created_at: DateTime.now.all_month)
                         .select('SUM(total) as total_sales')

  @previous_sales = Orders.where(created_at: DateTime.now.last_month)
                          .select('SUM(total) as total_sales')
  ...
end

In our controller, we’re retrieving the sales data from the current month and last month. It’s pretty simple, but note we’re making two database queries to get the data we need. Now, let’s take a look at the view:

<table>
  <thead>
    <tr>
      <th>This Month's Sales</th>
      <th>Last Month's Sales</th>
      <th>Difference</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><%= @current_sales.total_sales %></td>
      <td><%= @previous_sales.total_sales %></td>
      <td>
        <%= number_to_percentage(
          ((@current_sales.total_sales - @previous_sales.total_sales) / @current_sales.total_sales * 100) %>
        )%>
      </td>
    </tr>
  </tbody>
</table>

Okay merge the pull request because we’re done, right? Wrong. Although the above code solves the business problem, we’ve created a few more problems down the road:

The Problem

1. It’s slow. As mentioned before, we have to make two queries to the database just for this calculation and we’re using Ruby to do math which is slow.
2. It’s not reusable. If we want sales data somewhere else, we’ll have to write new code.
3. It’s limiting. We only have this month and last month’s data, but we know someone in the future is going want to see more.

SQL LAG function to the Rescue

Most popular databases have the LAG() function which gives us the ability look at the previous row for comparing data to the current row. This is perfect since we need to see previous month’s sales data to be able to calculate a percentage increase or decrease.

Let’s write our SQL code, but first, we’re going to wrap our SQL query into a plain Ruby object so that it’s easier to test and re-use. In some cases, I like to organize SQL queries into it’s own directory like /app/queries.

# app/queries/sales_data_query.rb

class SalesDataQuery
  def self.monthly_sales_report
    sql_string = %Q{
      WITH sales AS (
        SELECT
          date_trunc('month', created_at)::date AS order_month,
          SUM(order.total) AS total_sales,
        FROM orders
        GROUP BY date_trunc('month', created_at)
      ),
      sales2 AS (
        order_month,
        total_sales,
        SELECT LAG(total_sales,1) OVER (ORDER BY "created_at") previous_total_sales
        FROM sales
      )
      SELECT
        order_month,
        total_sales,
        previous_total_sales,
        (100.0*(total_sales - previous_total_sales) / NULLIF(total_sales,0)) percent_diff
      FROM sales2
      ORDER BY "created_at" DESC
    }

    ActiveRecord::Base.connection.exec_query(sql_string)
  end
end

The SQL looks a little complicated, but it’s doing a lot of work for us. It’s adding up total sales for this month and the previous months, plus it’s calculating the percent difference - all in one SQL statement. The results look like this:

order_month | total_sales | previous_total_sales | percent_diff
------------+-------------+----------------------+-------------
          1 |        2000 | 1099                 | 45.05
          2 |        1001 | 2200                 | -119.78
          3 |        3400 | 3000                 | 11.76
          4 |        9909 | 8920                 | 9.98
...

As you can see, we not only have this month and last, we have all the months in the database. Let’s go back to our code. In our controller, we make only one call to the database and we can loop through the results in our view with no math calculations this time.

# app/controllers/dashboard_controller.rb

def index
  @sales =  SalesDataQuery.monthly_sales_report
end

<table>
  <thead>
    <tr>
      <th>Month</th>
      <th>Sales</th>
      <th>% Difference</th>
    </tr>
  </thead>
  <tbody>
    <% @sales.each do |sale| %>
      <tr>
        <td><%= sales.month %></td>
        <td><%= sales.total_sales %></td>
        <td><%= number_to_percentage(sale.percent_diff)%></td>
      </tr>
    <% end %>
  </tbody>
</table>

Now this is a pull request we can approve!

This is just one example, but hopefully illustrates the point that knowing more about how utilizing SQL queries can simplify your Ruby code and make your application run more efficiently. I encourage you to take a closer look at the SQL language for your database of choice - there is a wealth of power yet to be realized.

Before Ruby, I was a Java programmer at a big tech company and before that I was a Perl programmer at a book publishing company. I always enjoyed the process of building software and at that time I was exploring all kinds of languages and tools. At the big tech company, the standard language was Java so that was the main language at the time. They sent me to a software conference in San Francisco in 2005 (I think), where I was eager to learn more about software design patterns, agile development, continuous integration, and all that came along with the enterprise world. One evening, they held an award ceremony called The Jolt Awards.

The Jolt awards awarded software creators in a variety of categories. One in particular was called “Best New Framework” or “Best Web Framework”, I can’t remember which. I sat in the audience where this young kid took the award for “Ruby on Rails”. This kid was approximately the same age as me, dressed like me, and didn’t look anything like the other award winners which were mostly older, not-so-well-dressed nerdy men. Needless to say, I was intrigued.

That night in the hotel, I installed Ruby on my laptop and was fascinate how easy it was to pick up an run simple commands. It was like my old Perl days, but with objects and easier to read. Eventually, I would get good enough and discover “the flow” and the utter joy of writing code. It allowed me to shift from primarily focusing on the mechanics of the language (Java at the time) to the actual features of the product - essentially going from “how” to “what”. Then, later learning more about the community behind Ruby and interesting characters and books like “why’s (poignant) Guide to Ruby” was icing on the cake.

It was more than just the language that spoke to me, it was the culture. It was a profound shift. A year or so later, I quit my big tech job and started my own consulting firm so I could write Ruby everyday. And for fourteen years, I did just that - building hundreds of applications with Ruby and getting paid for it. It has been one of the greatest endeavors of my life.

Today, I love Ruby as much today as I did seventeen years ago. Even though I’ve moved on from the consulting world, I still write Ruby almost everyday in some way shape or form. And I don’t see that changing anytime soon.

Thank you Ruby ❤️

When I was a technical leader at a big tech company, releasing software to production was a big deal involving many people and procedures - taking days sometimes weeks. It was particularly important to have all the i’s dotted and t’s crossed, otherwise it may take another week to deploy another release. In some cases, a small bug would slip through or even something smaller like a word misspelled that would have to wait until the following week or petition for an emergency release.

Another common scenario is an outside department in the company needs a special “view” to the application so that they can gain access to the software for their own purposes. They typically would request our team to build a separate section just for them tying up our resources just to build this special feature instead of focusing on our own customer needs. Does this sound familiar?

Over many years of taking feature requests working with customers and external teams, you begin to realize a common set of requests users always ask for post-production. In this post, I want to share with you what I typically like to include with every piece of software I ship in order to anticipate future requests and reduce the need to deploy special releases.

1. Administration Tool

By far the best and obvious way to make updates in production without re-deploying code is having an administration tool in place. This can be for development team eyes only or even allow customers to make updates as well. In Ruby On Rails applications, there are already a few great plugins that makes it very easy. Here’s just a few examples that have helped my team:

• Updating production database records like user information.
• Revoking user accounts or permissions.
• Removing fake or test account data.
• Changing the price of subscription plans.

2. A Private API

Building an API in the software can be pretty simple to include. Again, for Ruby on Rails apps, there are gems that make this simple. Having just a simple API in place and pay big dividends down the road. When asked to get a special “access” in a lot of cases, you can just provide the API endpoints and connection details and they can build their own application themselves.

3. Managed Tool for Error Logging

If I had a nickel for every time I got an email saying “the website was down last night” and then spending hours trying to figure out what happened, well, I’d have a lot of nickels. Having a way to search log files is a crucial way to track down issues or even false alarms. A lot of the time it’s the hosting provider having network issues. Tools like DataDog gives you the ability to track down errors and when they occur. If anything, it’s been a great way to point out there weren’t any issues at all and we can move on to the next task.

4. Healthcheck (aka Smoketest) Page

This is one of the oldest and my personal favorite trick. Often times I will build a page in the application that only I can get to (i.e. /smoketest) that will give me a basic vitals of the system. For example:

• First and foremost, make sure the application is still running.
• Show the number of active users to make sure the application is database connection is fine.
• Display the status of connection to third-party api’s to check the connection is working.

When getting that dreaded email saying “something’s wrong with the site”, I’ll check the smoketest page first to make sure all is working or quickly determine the issue.

5. Routine Maintenance Task Page

Similar to the administration tool, having a section in the application where the development team can queue routine maintenance tasks i.e. Rake tasks, is a great time saver. The folks at Shopify have a gem for this called Maintenance Tasks that works great. Here are some examples of maintenance tasks I’ve used in production before:

• Deleting inactive user records to clean up the database.
• Clearing production cache assets to make sure all cached assets are up-to-date.
• Re-running scheduled tasks in case there was an outage from the night before.

After your the application has been in production a while and you’ve implemented tools like listed above, you’ll notice fewer and fewer emergency releases and having more to time focus on adding value your customers will love.

Since having issues with my eyesight last year, walking has turned into something more. Walking as a pastime, walking without aim, walking with no destination. A state of no path to find a path, it’s what I call wanderment.

I’ve walked more in the past year than I have ever walked before in my life. Since being forced to severely reduce my screen time, I’ve gone back back outside and it has made me see earth and life in a different way (ironically). I just so happen to live in a beautiful part of the country with mountains, beaches, and city buildings, all within a few miles, so it was only natural that I walk every square inch.

Wanderment has become a large part of my therapy. Along the way, I’ve discovered some amazing benefits. Not just obvious physical benefits, but a substantial increase in levels of emotional and spiritual energy too. Here are just a few:

Reduces anxiety. Reductions in anxiety are subtle, but noticeable. During difficult times, just getting outside and walking for a few blocks (aimlessly) improves my mood and it’s my go-to way to feel better.

Clears out the cobwebs in the brain. I’ve noticed a increased level of function in my brain. Walking aimlessly without a goal, mission, or purpose, allows my brain to think about other things. Things I’ve not had time or energy to think about before.

Creativity boost. Related to cleaning out the cobwebs in the ol’ brain, having some extra space in the brain leaves room for creative ideas to naturally sneak in. Through many walks, I’ve come up with ideas, solved long-standing problems, and lofty goals seem more attainable.

Getting closer to calm. Most days, it’s completely chaos in my head. With all that’s happening in the world and the internal pressures relationships, career, family, etc., it can be all overwhelming. Wanderment, allows me to take a break from all that noise and re-center myself. I can focus on what’s really important in life.

We can go a little further. Here are a few activities I like to do that have greatly benefited me and how I get the most out of wanderment. Take time to listen to nature. Find a nice place to take break. Stop and just listen to what’s happening around you. Listen the birds, the leaves, the waves, etc. Feel the earth. Sit on the ground, dig your feet into the sand, brush your hands on over the grass. Deep breaths. Smell the salty air, feel the wind in your face.

Getting lost in the world, as it seems, has set me on a path to finding myself. I haven’t arrived by any means, but I feel like I’m in the right direction.

I’ve seen this countless times in my career when running a consulting company and when I worked for a big IT company. In this article, I want to share with you one technique I use to help pay down the technical debt and pave a path forward to a more sound development team using Rails Engines.

Quick intro to Rails Engines

The term “engine” can be confusing because it’s not really anything different than what we’ve already been working with. A Rails Engine is a Rails application with some special options that allow us to “hook” into it. I think of it as a Rails module (like a Ruby module) that we’re adding to our code, but instead of getting additional Ruby methods, we can a whole web application at our disposal.

This means we can pack a whole bunch of common/shared functionality into our engine including models, controllers, views, and even assets like Javascript, CSS, and image assets.

Let’s kicks things off with an example engine. Let’s say our company wants to build an engine called CompanyStack:

$ rails plugin new company_stack --mountable

We’re going to isolate our engine so that we can namespace our ruby code to avoid any collisions in naming. This will help our engine be independent from any application that uses it. It’s important to think of our engine as completely separate from any application that uses it. Combined with the --mountable option (above), using the isolate_namespace will provide independence we need:

# lib/company_stack/engine.rb

module CompanyStack
  class Engine < ::Rails::Engine
    isolate_namespace CompanyStack
  end
end

Now we can include our engine in our Rails application’s Gemfile:

gem "company_stack", path: "../path/to/company_stack"

Let’s say our company has a few Rails applications in production. Upper management is complaining about the amount of time it takes to ship code. Some of our new engineers aren’t as familiar with older versions of Rails so it’s more difficult to assign team members to projects. Our senior engineers are complaining about the sheer amount of redundant code across our projects. Our Devops team wants to upgrade our servers, but can’t because some applications can’t run on newer versions of Ruby, SSL, Postgres, etc etc. Sound familiar?

What are our goals with making our development team more efficient?

1. Reduce the overall development churn so we can ship new features faster.
2. Provide a clear direction on our company’s official technical stack.

Using Rails Engines to Define Our Organization Stack

Do we know our company’s official technology stack? We hope that it’s Ruby, but what about the gems and libraries we should be using? This is crucial in keeping our applications consistent. How many times have we come across a project that uses Rspec and another one using Minitest? It’s important to define what and how we should be writing our applications so that we can keep our code consistent and reduce the context switching. A good place to start is the gemspec file in our engine:

# /company_stack.gemspec

Gem::Specification.new do |spec|
  spec.add_dependency 'rails', '>= 7.0.3.1'
  spec.add_dependency 'turbo-rails', '~> 1.0.1'
  spec.add_dependency 'hotwire-rails', '~> 0.1.3'
  spec.add_dependency 'pg', '>= 1.3.5'
  spec.add_dependency 'view_component', '~> 2.53.0'
  spec.add_dependency 'redis', '~> 4.8'
  spec.add_dependency 'cssbundling-rails', '~> 1.1.1'
  spec.add_dependency 'jsbundling-rails', '~> 1.0.2'
  spec.add_dependency 'bcrypt', '~> 3.1.18'
  spec.add_dependency 'puma, '~> 5.6'
  ...
end

Here we are defining that Rails 7 with Hotwire, Postgres, Redis, and Puma as our official stack. We can include additional gems like Mintest, Devise, Sidekiq - you name it. This is taken from my own company’s official stack and it means all Rails applications that includes the CompanyStack engine must be written with these tools - no Rspec, no Mysql, no fancy Javascript libraries unless officially approved. If your company’s Rails applications are older, then it most likely makes sense require lesser versions of Rails, say 6 and up until everything is caught up.

Central Place for Shared and Common Code

Once we have our engine installed on our Rails applications, we can begin to explore ways to reduce code redundancy. Of course, each application is unique, but there will always be cases of common code. For example, most applications has a User model and that can be one area to extract common functionality.

Here’s a simplified example: We’ve looked at a few of our Rails applications and we’ve noticed that we’re authenticating the User in multiple ways. As an organization, it would be nice that all our projects authenticate the same way so we know that our applications are secure and up-to-date. We’ll create a Concern in our engine that authenticates a user using email and password.

# /app/models/concern/company_stack/users/auth

module CompanyStack
  module Users::Utils
    extend ActiveSupport::Concern

    class_methods do
      def login(login, password)
         ...
      end
    end
  end
end

Now, all we have to do is include the Concern in our Rails application and we instantly have a way to authenticate user records. Eventually, we can remove the old code from the application and just use the engine to authenticate our users.

class User < ApplicationRecord
  include CompanyStack::Users::Authentication
  include CompanyStack::Users::Utils
  ..
end

#=> current_user = User.login("mattsears", "******")

This is a very simplified example, but hopefully it illustrates the potential in using Rails engines as a way to cut down technical debt. The nice thing about using Concerns, is that our applications aren’t required to use the new authentication until they’re ready i.e. including include CompanyStack::Users::Authentication in our User model. The additional bonus is we don’t have to rewrite the user authentication for any new applications we create.

We’re not just restricted to sharing Ruby code either, we can share assets like Javascript and stylesheets as well. At my company, our official front-end stack is Hotwired and TailwindCSS and so we can include these libraries in our engine’s asset pipeline.

// package.json (in CompanyStack)

{
  "dependencies": {
    "@hotwired/stimulus": "3.0.1",
    "@hotwired/turbo-rails": "^7.1.1",
    "@rails/actioncable": "^6.1.5",
    "@rails/activestorage": "^6.1.5",
    "esbuild": "^0.15.6",
    "postcss": "^8.4.6",
    "postcss-flexbugs-fixes": "^5.0.2",
    "postcss-import": "^14.0.2",
    "postcss-nesting": "^10.1.2",
    "postcss-preset-env": "^7.3.1",
    "tailwindcss": "^3.0.20"
  },
  "scripts": {
    "build:css": "tailwindcss --postcss -i ./app/assets/stylesheets/company_static/application.css -o ./app/assets/builds/company_stack/application.css",
    "build": "esbuild app/javascript/*.* --minify --bundle --outdir=app/assets/builds/company_stack"
  }
}

Speaking of asset pipelines, we can also include custom stylesheets for example, that match our company brand and/or we can also include Stimulus controllers that provide common Javascript functions. Now, all we have to do is include the assets in our applications layouts:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <!-- CompanyStack Engine's assets -->
    <%= stylesheet_link_tag 'company_stack/application', media: 'all' %>
    <%= javascript_include_tag 'company_stack/application'  %>

    <!-- This application's assets -->
    <%= stylesheet_link_tag 'application', media: 'all' %>
    <%= javascript_include_tag 'application'  %>
    ...

And now our Rails application includes all of our company’s official front-end stack and is ready to take advantage of all the code that has already been written - keeping our Rails applications not only using less code, but looking consistent too.

We don’t have to stop here either, we can include application helpers, background workers, view components, and more in our engine.

In Review

Hopefully I’ve illustrated the power as using with Rails Engines as an overall strategy to help your organization get on the right track with more maintainable applications. For my company, we’ve been using this strategy for a while and it has paid a lot of dividends and I think it can help you’re team too.

1. Pick a project that gives you the most energy.
2. Only work on what will ship with version one.
3. Run the project like you’re part of a team.
4. Enjoy your work.

Follow Your Energy

I’m at a certain age where I’ve been around the block a few times. New technology and tools don’t excite me as much as they used to. No longer can I slug through a boring project with the energy gained from learning a new programming language or framework. Don’t get me wrong, I still enjoy learning new things, but I’ve learned to love mastering my current set of tools even more. I can start a new project knowing exactly how it should be built - like a lumber jack and a sharp axe, I know how to chop this tree down. This paired with a new brand new idea, I have all the energy I need.

Bare Minimum Prototype

Ideas have a way of spreading like wildfire. The key here is keeping a list of everything you want your project to accomplish. Now cut that list to the bare minimum for the initial release and that’s what you will work on first. The rest goes into the backlog. Whenever you get a new idea, put it in the backlog so you don’t keep that idea in your head. Getting your first working prototype deployed to production is the hardest part of any project. Having too many ideas stored in your brain kills momentum and can cause you to second-guess decisions.

Project Management for One

Now that you have your tasks separated into a backlog, we can plan out our project. Even if I’m the only one working on the project, I still use a fancy project management tool to keep track of progress. I could easily work off some note cards or a spreadsheet, but I still queue my tasks in a software tools build for teams. Tools like Github Project, Jira, or in my case, Asana which I’ve used for years while running a consulting firm. Why you may ask? For starters, it feels more familiar to me and it’s proven successful in previous projects, but most of all, it keeps me accountable to myself. I assign a task to myself with a deadline, and this gives me a complete roadmap. Asana sends me a few reminders when things are due and I can tick them off one-by-one. I promise you, at the end of the week, you will feel proud seeing the list of complete tasks.

It’s Not a Race

Truly rewarding work is work you are proud of, not how fast you do it. As I always say, you will be remembered for the work you put into this world, not that you got it done on time. Deadlines come and go, but the work is what persists in time. So it’s okay that you missed that target date so long as you are enjoying the process. That is the joy of side-projects after all. Make your side projects fun and you will complete them every time.

1. Emacs

Those who know me, could have guessed this one. I’ve been a Emacs users for over twenty years - ever since starting out programming in Perl all those years ago. Since then, I’ve customized and maintained my configuration for web development and more specifically for Ruby / Rails development.

2. Tmux with Tmuxinator

I live in the terminal all day long - writing, coding, notes and more. Tmuxinator is by far the most used Ruby gem in my arsenal and helps me manages all my Tmux sessions with a simple YAML configuration file. Each Tmux session is a project more-or-less and inside each session I have windows and panes usually dedicated to a single task or context. Let’s take a look at an example, here is a Tmuxinator configuration for a typical Ruby on Rails project:

name: super-duper-project
root: ~/Workspace/active/super-duper
windows:
  - editor: emacsclient -t README.md
  - shell: clear
  - console: rails c
  - testing:
      layout: even-horizontal
      panes:
        - emacsclient -t test/test_helper.rb
        - bundle exec guard
  - logs: tail -f log/development.log
  - workers: dev

When I run tmuxinator super-duper-project in the terminal, Tmuxinator fires up Tmux and creates six windows in the project directory:

1. editor: Starts and Emacs session by opening up README.md file to get things started.
2. shell: Used for mostly running rake and rails commands.
3. console: Starts a Rails console session for code exploration.
4. testing: Starts an Emacs session in the test directory and splits the window with guard that watches for changes in test files and runs tests automatically as I update the code.
5. logs: Tails the development log so I can see requests and errors.
6. workers: Runs commands in the Procfile.dev file like the Rails server, yarn, and background workers.

Here is another configuration for this very website. I use Jekyll for this blog and have three windows setup. With command tmuxinator website, I can jump right into the project, run bundle exec jekyll draft "My new draft", in the shell window, start the Jekyll server, and start writing.

# ~/.tmuxinator/website.yml

name: website
root: ~/Workspace/active/website
windows:
  - editor: emacsclient -t README.md
  - shell:
  - server: bundle exec jekyll serve --drafts --livereload --livereload_port 8888

3. Minitest

I’ve written many times about Minitest and it’s been my standard testing framework for a long, long time. It’s strength is it’s simplicity, which results in a simpler test suite. Having a simple and straightforward test suite is crucial for long-term success. Here is an example of a simple, yet beautiful test:

# frozen_string_literal: true

require 'test_helper'

class DateTimeHelperTest < ActiveSupport::TestCase
  include DateTimeHelper

  let(:date_range) { nil..nil }

  subject { format_date_range(date_range) }

  describe 'with no range at all' do
    it 'does not format date' do
      assert_equal 'Anytime', subject
    end
  end

  describe 'with a date range on the same day' do
    let(:date_range) { DateTime.new(2022, 10, 12, 8)..DateTime.new(2022, 10, 12, 9) }

    it 'formats the date range on same day' do
      assert_equal 'Oct 12, 2022 08:00am - 09:00am', subject
    end
  end
end

4. Guard

As I mentioned in my Tmuxinator config above, I run Guard continuously in the background. Specifically, it watches for any changes to the code and runs related tests. Here is a real example Guardfile I have in most projects:

# frozen_string_literal: true

ignore %r{.git\/*},
       %r{public\/.*},
       %r{solr\/.*},
       %r{vendor\/.*},
       %r{tmp\/.*},
       %r{log\/.*},
       %r{coverage\/.*}

guard(
  :minitest,
  spring: 'bin/rails test',
  all_on_start: true,
  all_after_pass: true,
  grace_period: 3.0
) do
  watch(%r{^app/(.+)\.rb$}) { |m| "test/#{m[1]}_test.rb" }
  watch(%r{^app/controllers/(.+)_controller\.rb$}) { |m| "test/integration/#{m[1]}_test.rb" }
  watch(%r{^app/views/(.+)_mailer/.+}) { |m| "test/mailers/#{m[1]}_mailer_test.rb" }
  watch(%r{^test/test_helper\.rb$}) { 'test' }
  watch(%r{^test/.+_test\.rb$})
end

When any tests fail, I’m immediately notified and I hop into the ‘testing’ tmux pane and can see which tests are failing and fix it fast.

5. Amazing Print / Pry

At the same time as I’m fixing tests or writing new tests, each time I save a file, Guard re-runs the test giving me instant feedback. A lot of the time, I need to see what is being returned and Amazing Print comes in handy for this reason. I can simply add the line ap subject to the test and save the file. Guard will rerun the test and amazing print will print the results in full color. If I need to dig deeper, I can also drop in binding.pry, and Guard will “suspend” execution and let me Pry open the code for a closer look.

6. Rubycop

Rubocop is a static code analyzer and code formatter that helps me make sure I’m keeping inline with best practices thus increasing code health and maintainability. I have Rubocop integrated with my Emacs config that allows me to see in real-time any violations and/or recommendations on how the code could be written better. Plus paired with extensions like rubocop-rails, rubocop-performance and rubocop-minitest, I can get recommendations immediately for specific libraries and frameworks.

7. Simplecov

SimpleCov let’s me see how well my tests are covering the application code. SimplCov produces results in a very well organized html page where I can see pieces of code that didn’t get “touched” marked in a shade of red. I can write tests specifically that touches that code or remove the code if it’s not being used. It some cases, if the code isn’t touched, it means it’s not being used and I can remove the code all together keeping the project nice and tidy.

There are quite a few other tools that I didn’t mention, but the above seven tools form a solid base on what I use every day for Ruby/Rails development. I’ve enjoyed this particular setup for over a decade and will mostly like continue this setup for the next decade.

Company Acquisition Complete

First and foremost, my consulting company of fourteen years was acquired and completed the full turn-over in June. I am so incredibly proud that the transition was a huge success and I can’t be more excited about the results. It was a great learning experience to know what it means to prepare, negotiate, and plan for a acquisition successfully.

Running and operating a technology consulting company over the past 14 years has been the biggest journey of my life. I could have never imagined what the company evolved to when I first decided to quit my “big tech” job and venture out on my own. I’ve learned a tremendous amount, not only in all aspects of business, but in interpersonal skills, leadership, how to roll with the punches and the importance of celebrating milestones just to name a few.

Peace out Eyesight

Now for the lowlight of the year, in early summer, my eye vision suddenly started failing in a big way - no doubt from heavy screen use from the pandemic. I was forced off all screens for what felt like an eternity. I’m so thankful as I sit here and write this post in my beloved Emacs, that I’m back armed with my new glasses ready to work. It’s a life-altering event to say the least. I’ve joined the exclusive club of people that are always looking for their glasses.

Relaxing at the beach in the San Juan islands

The positive side effect of losing temporary eyesight is that it forced me off the screens (and also social-media) and back in touch with the analog life. Getting back to nature, I gained a real appreciation for the gifts that have been here all along. I spent many days at the beach, hiking, paddle-boarding and road trips. Not being tethered to my phone all the time was absolutely liberating. Even though I’ve gained my eyesight back, I continue to spend less time online and more time being present in real life.

Hotwire, Ruby on Rails, View Components, and Tailwind CSS

Most posts this past year have been about these topics and most of the year I spent writing and learning on what I called the new era of Ruby on Rails development. It is fantastic. Many thanks to the fine folks at Basecamp and Rails team for ushering in a new way of writing Rails applications. Those that know me, know I’ve never been a fan of writing SPA apps and the amount of JavaScript required is absurd. So when Hotwire and Turbo were released, it was a very welcome addition.

Paired with ViewComponents, it feels like another natural addition to the Rails toolbox. Throw in Stimulus and Tailwind CSS, it feels like discovering the joy of web development all over again.

Favorite books and podcasts

I’ve written about a couple books on finance that have really affect my outlook on investing in a very positive way. In addition to these books, I’ve listened to many many books and podcasts while my eyesight was on hiatus. Here are just a few of my favorite this year.

Books

1. Notes on a Nervous Planet
2. Traction: Get a Grip on Your Business
3. Unfu*k Yourself: Get Out of Your Head and into Your Life
4. The Psychology of Money: Timeless lessons on wealth, greed, and happiness

Podcasts

1. One Year
2. MicroConf On Air
3. Office Ladies
4. The Rework Podcast

What I look forward to in 2022

I generally don’t set new year resolutions or any new year goals for that matter. I believe that should be done throughout the year. But, what I like to do is set intentions for the year in hopes to shape and navigate the year to come. So this year, I want to set an intention to focus on mental and physical health first and foremost.

I really look forward to doing what I love to do. For work, this means creating and building things from my own ideas in hopes it will help people in their own lives and businesses. For my mental well-being, I want to continue connecting with nature and continue my exercise regiment. Last, but not least, I want to make new and stronger connections to friends and loved ones in this new year. I’m really hopeful we all can make stronger connections again this year.

Happy New Year everyone! I hope you all have a happy and healthy 2020.

This is especially true for new Rails developers - too eager to reach for a gem for every new feature they write. When there are too many gems, the app will run slower since there are more lines of code to process. Why is this? Typically gem authors need to accommodate for a variety of factors. Factors like Ruby versions, database types, or web frameworks like Sinatra. What this means is there is a lot of extra code in that gem that will never be used by our application. Many times, I’ve seen a Rails app just use on method from a single gem!

Three questions I ask when deciding to use a gem or not:

1. Is it currently being maintained?

Take a look at the source code on Github or Gitlab. What is the date of the last commit? Does the author explicitly state that the gem is no longer maintained? If there hasn’t been a commit in the last year, it’s most likely not being updated. So we can’t expect bug fixes or security updates in the near future. It will may also mean that we risk preventing other gems from being updated. For example, running bundle update on our Rails project may not run since the unmaintained gem depends on other older gem versions.

2. What is the size of the gem?

How big is the project? What other gems does it depend on? Browse through the source and get a rough idea about the amount of code. There might be a lot of code to handle a variety of environments or it may not be as organized or designed well. Why is this important? More gems means more Ruby and more Ruby means a slower running app.

3. How much of the gem do we need to utilize?

What do I need from this gem to get our feature complete? Do we just need one or two small things to get the job done or do we need something more comprehensive like Devise or ViewComponents. Obviously, if we need a gem that is more comprehensive, then we should use the gem. A gem like ViewComponents is a large project and would require a lot of code to mimic the functionality and it’s more or less closer to the core of our application.

Case Study

I recently had the need for the ability to save a draft of data before saving it to the real database record. Simply put, I need to stash a set of data that mocked my real ActiveRecord model’s schema and save it to a database until the users decides to publish it.

After some searching, I found a couple gems that do exactly what I need. However, none of them have been updated in the last year. The most popular of the gems is actively looking for a new maintainer and it has a bunch of overly complicated code that I most likely will never need. In my case, I only need to save a draft and publish the draft - that’s it.

If you haven’t guessed by now, I’ve decided not to use any gem and write my own code to do what I need. I’m going to approach this as a reusable code in case we want to use drafts in our other models. I’ve also looked at the source code of the gems to get ideas and use them in my own code.

Let’s create a concern called Draftable:

# apps/models/concerns/draftable

module Draftable
 extend ActiveSupport::Concern

 included do
   has_one :draft, as: :draftable, dependent: :destroy
 end

 def has_draft?
   Draft.exists?(draftable_id: id)
 end

 def save_draft(params = nil)
   return false if new_record?

   if has_draft?
     update_draft(params)
   else
     create_draft(params)
   end
 end

 def publish!
   ActiveRecord::Base.transaction do
     self.attributes = draft.reify.attributes
     self.save
     self.reload
     draft.destroy
   end
 end

 private

 def create_draft(_params = nil)
   with_transaction_returning_status do
     draft ||= Draft.new
     draft.object = ActiveSupport::JSON.encode(attributes)
     draft.draftable_id = id
     draft.draftable_type = self.class.name
     draft.save
   end
 end

 def update_draft(params = nil)
   with_transaction_returning_status do
     values = ActiveSupport::JSON.decode(draft.object)

     params.each do |key, value|
       values[key.to_s] = value
     end

     draft.object = ActiveSupport::JSON.encode(values)
     draft.save
   end
 end
end

We’ve made this concern so that any model can have a draft. Here, we’re storing data in the object field using JSON objects. We do this with a polymorphic relationship to a Draft model:

# app/model/draft.rb

class Draft < ApplicationRecord
  belongs_to :draftable, polymorphic: true

  validates :object, presence: true

  def reify
    attrs = ActiveSupport::JSON.decode(object)

    attrs.each do |key, value|
      if draftable.respond_to?("#{key}=") && !key.end_with?("_count")
        draftable.send("#{key}=", value)
      end
    end
    draftable
  end
end

Now we can make any model have a draft. For example, let’s say we’re building a blog and we have a Post model that holds the article. I can simply include a Draftable module in my model:

# app/models/post.rb

class Post < ApplicationRecord
  include Draftable
  ...
end

With that, we can do things like post.save_draft(body: 'First draft of the article') to save a draft and @post.publish! to save the draft data to the posts table.

To summarize, the point of creating Draftable is to illustrate the decision not to use a gem even if one exists. With roughly a hundred lines of code (not counting our tests), we’re able to complete our feature and extend our app functionality by allowing any model to have a draft. In addition, we’re not dependent on another gem or it’s dependencies. We’re using less Ruby and so our app is lean and more maintainable.