annotateでカラム情報を可視化してみた
スキーマファイル迷子にならない！annotateを使ってみよう
annotateはその名の通り、注釈（コメント）を付けてくれるgemです。
このgemを導入しようと思ったきっかけは、初めてチームでECサイトを開発したときのことでした。
「カラム名と型って本当にこれであってたっけ...?」
と何度もスキーマファイルを開いていて、もうデスクトップの壁紙をスクリーンショットをしようかと思っていたぐらいでした。それくらい頻繁に確認していたので、効率の悪さを強く感じていました。
もちろん定義するのにチーム全員で確認し合っていますが、量も量ですし自分が全て名付けたわけではないので高確率で名前とか細かいところを間違えていたんですよね。
このgemを入れることによって何度もファイル間を行き来する手間が省けるので同じ悩みを持っている方におすすめです。
使用方法
インストール
group :development doは開発環境のみで使う記述です。
Gemfileの1番下に以下の記述を付け加えます。
group :development do
gem 'annotate'
end
おなじみの bundle install を実行しましょう。
bundle install
これでannotateが使えるようになりました。
スキーマの情報を書き出すには
このコマンドを打ってみましょう。
$ bundle exec annotate
キレイに整えられていてとても見やすい
モデルファイルの冒頭に、Schema Info としてテーブル構造の情報（カラム名・型・インデックスなど）がコメントアウトで追記されました。
削除するにはこのコマンドを打ちます。
$ bundle exec annotate --delete
手動でコメント部分を選択した後に削除しても特に問題はなかったです。
カスタマイズしよう
私は特に変更せずデフォルトのannotateを使っていましたが、注釈の記入位置など自由に設定することも可能です。
設定するためのファイルを作成するため以下のコマンドを打ちます。
$ rails g annotate:install
create lib/tasks/auto_annotate_models.rake
作成されたファイルがこちらです。
position_in_class を 'after' に変更すると、コメント部分を先頭から最後に変更できます。
# NOTE: only doing this in development as some production environments (Heroku)
# NOTE: are sensitive to local FS writes, and besides -- it's just not proper
# NOTE: to have a dev-mode tool do its thing in production.
if Rails.env.development?
require 'annotate'
task :set_annotation_options do
# You can override any of these by setting an environment variable of the
# same name.
Annotate.set_defaults(
'active_admin' => 'false',
'additional_file_patterns' => [],
'routes' => 'false',
'models' => 'true',
'position_in_routes' => 'before',
'position_in_class' => 'before',
'position_in_test' => 'before',
'position_in_fixture' => 'before',
'position_in_factory' => 'before',
'position_in_serializer' => 'before',
'show_foreign_keys' => 'true',
'show_complete_foreign_keys' => 'false',
'show_indexes' => 'true',
'simple_indexes' => 'false',
'model_dir' => 'app/models',
'root_dir' => '',
'include_version' => 'false',
'require' => '',
'exclude_tests' => 'false',
'exclude_fixtures' => 'false',
'exclude_factories' => 'false',
'exclude_serializers' => 'false',
'exclude_scaffolds' => 'true',
'exclude_controllers' => 'true',
'exclude_helpers' => 'true',
'exclude_sti_subclasses' => 'false',
'ignore_model_sub_dir' => 'false',
'ignore_columns' => nil,
'ignore_routes' => nil,
'ignore_unknown_models' => 'false',
'hide_limit_column_types' => 'integer,bigint,boolean',
'hide_default_column_types' => 'json,jsonb,hstore',
'skip_on_db_migrate' => 'false',
'format_bare' => 'true',
'format_rdoc' => 'false',
'format_yard' => 'false',
'format_markdown' => 'false',
'sort' => 'false',
'force' => 'false',
'frozen' => 'false',
'classified_sort' => 'true',
'trace' => 'false',
'wrapper_open' => nil,
'wrapper_close' => nil,
'with_comment' => 'true'
)
end
Annotate.load_tasks
end
他には出力形式、コメントの書き出し許可の変更もできるようですね。
補足
実はannotateにはルーティング情報も書き出してくれる機能もありましたが、Rails 6以降、ルーティング確認コマンドの仕様変更により、annotateによるルーティング情報の自動出力がうまく機能しなくなったようです。
自力で使えるように方法もあるようなので余力があればやってみたいですね。
参考にさせていただいた記事
最後に
構造がシンプルなアプリや、1人で開発していてカラム名もルーティングも自分の頭に入ってるぞ〜って方はこのgemにはあまり良さを感じないかもしれません。
実際、チーム開発の反省を活かして、ポートフォリオ制作時に導入したものの、それほど活用する機会はありませんでした。
あとは前述の通り、更新がしばらくないgemということも少しネックに思う人もいるかもしれません。
使用環境
- macOS sequoia 15.4.1
- zsh 5.9
- Rails 6.1.7.10
- ruby 3.1.2
- VS Code 1.98.2
Discussion