Railsプロジェクトにカラムのコメントを一括追加して開発者を笑顔にする

システム開発チームの村上です。

開発する中で実装者にしか分からないようなカラムが存在していて困っているといったことはないでしょうか。
もちろんカラム名だけで意味が伝わることが大切だと思いますが、なかなか思うように伝わらないのが現状。。。

そこで、この問題を解決してくれるカラムコメント一括追加という魔法の手順を紹介します。

大まかな流れはこちら。

1. プロジェクトからテーブル名, カラム名をCSVで出力する
2. CSVで出力したものをスプレッドシートで展開し、コメントを書き込んでいく
3. スプレッドシートに書き込んだものをマイグレーションファイルに反映させる
4. マイグレーション実行

では順番にやっていきます。

1. プロジェクトからテーブル名, カラム名をCSVで出力する

まずはRailsコンソールで下記スクリプトを実行して、id, created_at, updated_atを除くカラム名をCSVファイルとして出力します。

require "csv"
REJECT_COLUMNS = %w(id created_at updated_at)
file = "#{Rails.root}/columns.csv"

CSV.open(file, "w") do |text|
 text << ["テーブル名", "カラム名", "カラムコメント"]
 ActiveRecord::Base.connection.tables.each do |table|
   ActiveRecord::Base.connection.columns(table).each do |instance|
     text << [table, instance.name, instance.comment] unless REJECT_COLUMNS.include?(instance.name)
   end
 end
end

出力結果がこちら。

(columns.csv)
テーブル名,カラム名,カラムコメント
carousels,name,
carousels,priority,
carousels,is_visible,
carousels,transition_url,
carousels,image_id,
...
...
# 略

2. CSVで出力したものをスプレッドシートで展開し、コメントを書き込んでいく

上記で出力したCSVファイルをスプレッドシートで開くとこのようにテーブル名, カラム名, コメント名の列を持つシートが出来上がります。
これに人力でカラムコメントを書き込んで行きます!
ちなみに弊社ではCTOがほぼ全てのコメントを書き込みました。(約550個！)

3. スプレッドシートに書き込んだものをマイグレーションファイルに反映させる

先程コメントを書き込んだスプレッドシートをCSVでエクスポートしてから、下記スクリプトをRailsコンソールで実行してカラムコメントを付与するためのメソッド(change_column_comment)に引数を渡して出力します。

require "csv"
csv_data = CSV.read("./columns.csv")
File.open("./migration_file.rb", "w") do |file|
 csv_data.each do |row|
   text = "change_column_comment(:#{row[0]}, :#{row[1]}, '#{row[2]}')\n"
   file.write(text)
 end
end

出力結果はこちら。
これらをマイグレーションファイルに貼り付けます。

   change_column_comment(:carousels, :name, from: nil, to: "名前")
   change_column_comment(:carousels, :priority, from: nil, to: "表示順序")
   change_column_comment(:carousels, :is_visible, from: nil, to: "表示するかどうか")
   change_column_comment(:carousels, :transition_url, from: nil, to: "遷移先url")
   change_column_comment(:carousels, :image_id, from: nil, to: "FK:画像ID")
   ...
   ...

4. マイグレーション実行

最終的に出来上がった下記のようなマイグレーションファイルをもとにマイグレーションを実行して完成となります。

class AddComment < ActiveRecord::Migration[6.1]
 def change
   # change_column_comment(テーブル名, カラム名, from: 現在のカラムコメント, to: 反映させるカラムコメント)
   change_column_comment(:carousels, :name, from: nil, to: "名前")
   change_column_comment(:carousels, :priority, from: nil, to: "表示順序")
   change_column_comment(:carousels, :is_visible, from: nil, to: "表示するかどうか")
   change_column_comment(:carousels, :transition_url, from: nil, to: "遷移先url")
   change_column_comment(:carousels, :image_id, from: nil, to: "FK:画像ID")
   
   # ...略
 end
end

下記の画像がデータベースのドキュメントを出力したものですが、
きちんとCommentsの列にコメントが追加されていい感じそうです！

おわりに

今回のカラムコメント追加で、よりストレスなく開発ができるようになり、解釈を間違えて実装してしまうことも防げるようになったと思います。

それぞれのカラムには開発者の想いが込められており、想いをこめ過ぎた結果、そのカラムにどのような意味があるのかわからなくなっているということやエンジニアの笑顔が見たい！ということがあれば活用していただけると幸いです。ありがとうございました。