これは Git (や Subversion などのバージョン管理システム) にコミットする時により良いコミットメッセージを書くための提言です。この提言は特にメッセージの一行目だけを対象とします。せめて最も重要な一行目だけでも良いメッセージを書いて欲しいからです。提言をズバリ一言で表すと 一行目には要求仕様を書け です。
背景
プロジェクトによっていろいろ慣習の差はあるものの、一般的には「コミットメッセージの一行目は変更内容の要約を簡潔に書け」とされます。特に Git は、各コミットメッセージの一行目だけを取り出してそれを一覧表示するなど、一行目を特別に処理する機能が多いので、一行目にできるだけ多くの情報を凝縮させることは重要です。またメッセージを一行しか書かない不届きな慣習のプロジェクトでは、十分な情報を持たないメッセージは無用の長物と化します。
良くないコミットメッセージ
しかし私は、情報量が少なすぎて分かりにくいコミットメッセージの実例をたくさん見てきました。
あまり良くないコミットメッセージの例:
- Fixed a bug where users can't log in correctly (ユーザが正しくログインできないバグを修正した)
- Changed how to show thumbnail images (サムネイル画像の表示法を変更した)
どちらも割と抽象的なメッセージで、もっと詳しく書ける様に見えます。特に「Fixed a bug where (バグを修正した)」「Changed (変更した)」の部分にはほとんど情報がありません。バグ修正や変更を目的としないコミットが一体どれほどありますか? その様な情報の薄い単語のために貴重なメッセージ文字数を消費してはいけません。しかもこの類の語句は (英語では) 大概メッセージの最初に出て来るので、メッセージを読んで理解する際に読み飛ばす手間を増やします。
この様な情報の薄い語句が出てくるのは、プログラマを主語にしてメッセージを書くからです。「プログラマがバグを修正した」「プログラマが表示法を変更した」云々。しかしプログラマが普段やることはせいぜい機能の追加・変更・削除・バグ修正程度でバリエーションがありません。だからいつも「Fixed (修正した)」とか「Changed (変更した)」とか同じ語句がメッセージに出てくるのです。
しかも fix や change といった動詞は目的語として「X を A から B に変更した」の X の部分を要求します。ところが X の部分は、プログラムのどの辺りに変化があったのか、大雑把な範囲の情報しか表しません。結果として、より具体的な変化の内容である「A から B に」の部分が書かれなくなります。
良いコミットメッセージ
さて、私たちプログラマはただ何となくプログラムを変更したりバグ修正したりするわけではないはずです。機能が未実装だったりバグが有ったりしてプログラムが満たすべき要件・仕様を満たさないから、プログラムを変更して満たす様にし、それをコミットするのですよね。
であれば、コミットメッセージであなたが伝達すべきことは、 そのコミットによってプログラムはどんな要件を満たすのか です。そしてプログラムの要件について述べる以上、メッセージは プログラムを主語とする動詞句 で書くべきです。(そして主語はいつもプログラムなので省略します)
良い例:
- Allow login passwords longer than 20 characters (20 文字より長いログインパスワードを認める)
- Recache password database after changing password (パスワード変更後データベースをキャッシュし直す)
- Animate thumbnail images when they appear (サムネイル画像が現れる時アニメーションさせる)
- Trim thumbnail images larger than 200x200 px (200x200 px より大きいサムネイル画像を切り落とす)
これで fixed とか changed などの定番な単語が出てくることは少なくなります。ほとんどのメッセージが異なる単語で始まる様になるので、より早くメッセージの内容を読み取ることができる様になります。
これらのメッセージは全て「プログラムの動作を『P しない』から『P する』に変更した」の形に解釈できます。そして実際にメッセージに書かれるのは P の部分だけです。つまり、大雑把な変更範囲ではなく、具体的な変更内容がメッセージに書かれることになります。
またこの書き方は一部の人が主張する「コミットメッセージは過去形や三単現ではなく原形・命令形で書くべき」とも符合します。むしろ「要求仕様を書け」は「プログラムに命令する口調で書け」と同義と言ってもいいです。
例外
リファクタリングや不要コードの削除はプログラムが要件を満たす様にすることを目的とするコミットではありません。この様なコミットはこの提言の対象外です。