How to improve the documentation of your Ruby on Rails app
Enhancing Ruby on Rails Applications: Mastering Documentation with Rails-erd and Annotations Gems
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:
add
gem “rails-erd”
inside the:development
section of your Gemfile.rbexec
bundle install
on your terminalexec
bundle exec erd
on your terminal to generate the erd<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 an 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:
Add
gem 'annotate'
to your Gemfile.Run
bundle install
to install the gem.Use the command
bundle exec annotate
to automatically generate annotations for your models and tests based on the current schema and existing test cases.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!