How to improve the documentation of your Ruby on Rails app

When creating a Rails application is very easy, due to the Rails conventions, the application gets big and with messy contexts. Today I’m going to bring two gems to avoid this happening, at least in the documentation aspect: rails-erd and annotations.

Rails Erd

Creating Entity Relationship Diagram of the app

The rails-erd gem is a gem that enables you to generate an ERD (Entity Relation Diagram) of or Rails app using your application schema.rb and the ActiveRecord.

For those who don’t know what an ERD is, in simple words, an ERD is a diagram that picks every entity of your application (in Rails: the models) and creates a diagram showing each one’s attributes and how they interact with each other. It’s a very common tool to understand how the application works behind the scenes. Here is an example of an ERD generated by the rails-erd:

To install and use the rails-erd just follow the instructions here:

1. add gem “rails-erd” inside the :development section of your Gemfile.rb
2. exec bundle install on your terminal
3. exec bundle exec erd on your terminal to generate the erd
4. <optional>: exec bundle exec rails g erd:install on your terminal, this way every time you make a migration it will update the ERD.

Annotations

Enhancing code readability with inline documentation

The annotations gem is a powerful tool for Ruby on Rails developers aiming to improve the readability and maintainability of their codebase. This gem allows you to add descriptive annotations directly in your models, tests, fixtures, and factories, essentially anywhere in your code where clarification might be beneficial for future reference or for other developers working on the project.

Here is an example of how a example Post model is annotated using this gem:

# == Schema Information
#
# Table name: posts
#
#  id         :integer          not null, primary key
#  title      :string
#  body       :text
#  user_id    :integer
#  created_at :datetime         not null
#  updated_at :datetime         not null
#
# Indexes
#
#  index_posts_on_user_id  (user_id)
#
# Foreign Keys
#
#  user_id  (user_id => users.id)
#
# Annotations:
#  This model represents a blog post in the application. Each post belongs to a user.
#  - title: the title of the post
#  - body: the body/content of the post
#  - user_id: reference to the user that created the post
#

class Post < ApplicationRecord
  # Associations
  belongs_to :user

  # Validations
  validates :title, presence: true
  validates :body, presence: true

  # Additional logic, such as custom methods or scopes, can be added below.
end

Annotations can serve as a quick reminder of the purpose of a specific piece of code, explain why a particular decision was made, or provide a brief overview of how a complex function works. This practice encourages writing self-documenting code, reducing the need for external documentation and making the codebase much more approachable for new developers or when revisiting old code.

Here’s how to get started with annotations in your Rails app:

1. Add gem 'annotate' to your Gemfile.
2. Run bundle install to install the gem.
3. Use the command bundle exec annotate to automatically generate annotations for your models and tests based on the current schema and existing test cases.
4. Optionally, you can customize the behavior of the annotate gem by modifying its configuration file. This allows you to control which files are annotated and how the annotations are formatted.

That’s it, hope this helps you keep your Rails app better documented. See you in the next time!