今まで MySQL のカラムにコメントを付ける習慣がなかったんだけど，いざ新メンバーとして既存コードを読んで理解する立場になってみると，ちゃんと書かれたコメントのおかげでスキーマを理解しやすかったし，メンバー間の認識相違も生まれないし，重要だなと実感している．

確かに「コメントを付けないと理解できないならきっとテーブル設計やカラム設計に欠陥があるのでは？」という意見もあると思うし，それは否定しないけど，キレイに設計したとしても，ドメイン依存したコードやマジックナンバーもあるわけで，コメントを付けることが大きなメリットを生む場面は絶対にある．

Rails で試してみる

今はもう Rails を使ってないんだけど，Rails で MySQL のカラムにコメントって付けられるの？と思って調べてみたら，基本機能ではできなさそうだった．

`migration_comments` Gem を使う

migration_comments Gem を使うとマイグレーションを拡張できるようになる．

github.com

お決まりで Gemfile に追加して，テーブルはサンプルだけど，マイグレーションファイルを作成して流してみた．

gem 'migration_comments'

class CreateTasks < ActiveRecord::Migration
  def change
    create_table :tasks do |t|
      t.string :title
      t.integer :status, comment: '0: TODO, 1: DOING, 2: DONE'
      t.timestamps
    end
  end
end

status カラムにちゃんとコメントが付いていた．

mysql> SHOW CREATE TABLE tasks;
（中略）
| tasks | CREATE TABLE `tasks` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `title` varchar(255) DEFAULT NULL,
  `status` int(11) DEFAULT NULL COMMENT '0: TODO, 1: DOING, 2: DONE',
  `created_at` datetime NOT NULL,
  `updated_at` datetime NOT NULL,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 |
（中略）

`annotate` と組み合せる

migration_comments の README に annotate と組み合わせるとさらに良いよ！って書いてあったので試してみた．

github.com

同じく Gemfile に追加して，アノテートを流してみたら，ちゃんとモデルにコメント付きで書き出された．圧倒的に便利だ！

gem 'annotate'

# == Schema Information
#
# Table name: tasks
#
#  id         :integer          not null, primary key
#  title      :string(255)
#  status     :integer                                # 0: TODO, 1: DOING, 2: DONE
#  created_at :datetime         not null
#  updated_at :datetime         not null
#

まとめ

Rails のマイグレーションを使ってるなら migration_comments + annotate で幸せになれそう！

もっと早く知ってたら前のプロダクトで導入したかったなー．

あと migration_comments の README にメッチャ良いことが書いてあって「確かに！確かに！」って一人で頷いてたwww

Migrations are wonderful. They handle all your schema changes, and in a pinch they can bring any database up to speed. However, database schemas can change rapidly while a project is maturing, and it can be difficult to know (or remember) the purpose for each table and field. As such, they deserve to be commented. These comments should be available for display wherever those fields are found.