【Git】commitメッセージの書き方に迷ったとき(概要と理由)【943日目】

注意

あくまで私が気をつけていることなので、参考程度に

Gitなどを扱っていると、コミットメッセージを加えるときがありますが、
どんなコミットメッセージが良いか迷うと思います。

私が気をつけていることを記述してみます。

1行目に、今回の変更の概要
3行目に、今回の変更の理由

この2つを書いています。
ちなみに、重要なのは3行目の『理由』です。

概要を書く理由は何か。

コミットのツリーを見たときに、何が起こっているかの流れを把握したいときには、
1行目の概要を見ていくことになります。すると、コードで起こっていることを把握したくなるので、概要を書きます。

概要が並んでいると何がいいか。
あるコミットだけを打ち消したい(revert)
あるコミットだけを別なブランチに移動させたい(cherry-pick)

このような便利なコマンドを打つ際に、コミットの概要がわからないと、
コードを一個一個見ていく必要があるので、概要を書きます。

なぜ、変更を書く理由を書くか。

コードで何が起こったかは、コードを見ればわかります。
ボタンの色を変えたというコミットのコメントは、コードを見ればわかります。
複雑なものは、概要を書くことでカバー出来ます。

しかし、『なぜこの変更が必要だったか』は、コードを見て判断出来るとは限りません。
外部環境に影響されたために起こった変更だと、コードを見ても判断出来ません。

なので、『なぜ』をコメントに書くことで、
「あれ？このコード必要？」
って思っても、コミットメッセージで、必要と気がつけたりします。

このとき、何故を考えるときに、アンチパターンとなるものがあります。

『Aさんからのフィードバック対応』『Aさんから指摘されたので直す』

これは、コードを書いた人視点での『理由』です。
これは、コードに必要な理由でしょうか？
これがあったから、役に立つことはあるでしょうか。

【Aさんが、XXXをクリックしても動かないバグがあるとフィードバックしていたので直した】

この場合、『XXXをクリックしても動かない』から直すのではないでしょうか。
理由は、バグフィックスで、そのバグの内容を書くことになるでしょう。
あるいは、必要だから仕様追加したというコメントになるでしょう。

『○○さんからのフィードバック対応』が正しいときもあります。

【取引先の○○さんが、色が赤のほうがいいと言ったので対応】

この場合、赤がいいの理由が述べられていないので、取引先の○○さんが言ったというのが重要になります。

【取引先の○○さんが、色が赤のほうがいいと言ったので対応】
【Aさんが、XXXをクリックしても動かないバグがあるとフィードバックしていたので直した】

この2つにおいて、
もし、Aさんが変えてと言わなかったら、変える必要はないのでしょうか。
もし、取引先の○○さんが変えてと言ってなかったら、変える必要はないのでしょうか。

Aさんが変えてと言わなくても、バグなのですから、変える必要があるでしょう。
バグなのが理由、なのですから。

○○さんが変えてと言わなかったら、変える必要はないでしょう。
○○さんが言ったことが理由、なのですから。

このように、『それは本当に理由か』を考えて書くと、アンチパターンを踏みにくくなります。
迷ったら意識すると良いと思います。