GitやSubversion等のバージョン管理システムにおいて、コミットメッセージをいかに分かりやすく書くかというのは誰しも一度は考えるテーマかと思います。
そのために様々なフォーマットが提案されており、チーム内でルールを決めて運用されていることも多いと思います。この記事は特定のフォーマットやテンプレートを紹介するというより「どういう情報を含むべきか」を私なりに考え、まとめたものです。
5W1Hでの視点
この記事を書くにあたりネット上のいくつかの記事を参考にしましたが、メッセージに含む情報を考えるうえで、5W1Hの視点で整理している例が多いと感じました。
以下の3点についてはシステム側で自動記録されるため、特別な事情が無ければわざわざメッセージに記載する意味は無いと思います。
- Who(誰が): authorとして自動記録される
- When(いつ): タイムスタンプとして自動記録される
- Where(どこで): （変更箇所と解釈すれば）diffに自動記録される
よって、以下について必要に応じて記載していくことになります。
- What(何を): 何をしたか。タイトルとして記載されることが多い
- Why(なぜ): なぜそのような変更をしたか。議論の記録など
- How(どのように): 結果どのような修正をしたか。diffの要約など
Whatは例えば「○○を実装」や「△△を修正」というようにコミットのタイトルに記載されるでしょうから、これが書かれないことはほとんど無いと思います。
Howはdiffそのものであり「読めば分かる」ことから不要と言われることもあるようです。しかし変更の要約として記載するのは私はありだと考えています。単に「△△を修正」とだけ書かれているより「論理のミスを修正し～（△△を修正）」などとWhatを補足する目的で書くことで、後々コミットの要旨をすばやく掴みやすくなります。
Whyについてはよく重要性が指摘されており、他の5つの「見れば分かる」とは異なり、書かなければ欠落してしまう情報です。理由の直接記録だけでなくIssue番号など関連する情報をなるべく盛り込むべきだと思います。
よって、Whatは必須としつつ、補足情報としてHowやWhyを盛り込んでいく、というのが私が考える基本的な方針です。
時間軸での視点
そもそもコミットメッセージは何のために書くのでしょうか。いろいろな視点があると思いますが「現在の開発のため」と「未来の問題のため」という2つの時間軸で考えてみました。
- 現在の開発のため: 現在のチーム内で情報共有をするため。プルリクエスト（マージリクエスト）でどのような変更を行ったかをレビュワーに知らせるため。
- 未来の問題のため: 問題が発生した時に原因を分析するため。
実は前者に関しては、最悪何とかなることも多いと思います。不適切なメッセージをつけてしまっても担当者間で連絡を取ることもできますし、プルリクエストを作るときにリクエスト側のメッセージで補足したり、場合によっては詳細な資料を添付したりできるからです。
もちろんチームでフォーマットが決まっているならきちんと守るべきですし、丁寧に書けるならその方が良いのは当然です。ただ少なくとも「現在のこと」に関してはある程度リカバリーが効きます。
するとより重要なのは未来へ向けて、つまり問題が発生した時に状況を辿れるための手がかりを少しでも多く残すことだと思います。
自分の経験を振り返ってみても、コミットメッセージの付け方が問題になった時というのは「変更時期や変更者は分かるけど、どうしてそうしたのか、当時議論があったのか、ミスなのかが分からない」というような場合です。問題が起こらなければそもそもコミットを振り返ることは少ないです。
理路整然と要点をまとめることも重要な視点だと思いますが、迷うぐらいであればとりあえず情報を詰め込んでおく、ぐらいの方が後々役立つように思います。
まとめ
役に立つメッセージというのは以下のようなものだと考えます。
- すばやくコミットの要旨を掴めること: 明確なWhat、Howによる補足
- 変更の経緯を辿れること: Whyの記載や、情報へのリンク
例としては以下のような感じです。
〇〇を修正 #xxx ← 簡潔なタイトル(What), 関連情報(Why, issue番号等)
論理にミスがあり、意図しない条件で処理が行われていた。
ネストが複雑になり条件が分かりにくくなっていたため、条件式を抽出し整理した。
(どのように修正したか、Whatを補足する(How))その他、コミットの種類を分かりやすくするためにプレフィックスを使ったり、絵文字を使ったりというようなフォーマットが世間では提案されています。
十分な情報を含めたうえで、分かりやすいフォーマットを組み合わせることで良い履歴が残せると思います。
コメント