git等のバージョン管理システムにおいて、コミットメッセージをいかに分かりやすく書くかというのは誰しも一度は考えるテーマかと思います。
そのために様々なフォーマットが提案されており、チーム内でルールを決めて運用されている場合も多いと思いますが、この記事は何らかのフォーマットやメッセージのテンプレートを示すものではなく、やや抽象的ですが「どういう情報を含むべきか」というのを私なりに考えたものです。
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の記載や、情報へのリンク
このようにいつか問題が発生した時に役に立つか、という視点で「この情報は役に立つかも」という情報は積極的に盛り込んでいくことが大事ではないかと思います。
理路整然と要点をまとめて、というのも重要な視点だと思いますが、迷うぐらいであればとりあえず情報を詰め込んでおく、ぐらいの方が後々役立つように思います。
コメント