How to improve the documentation of your Ruby on Rails app
Tags: ruby, documentation, gems
Published: 2024-02-25 18:55:43

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.rb`
- exec `bundle install` on your terminal
- exec `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 a example Post model is annotated using this gem:

```ruby
# == 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.

## Getting 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 next time!