エンジニアのひよこ_level10

【毎日更新!】新卒4年目エンジニアブログです!

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

注意

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

コミットメッセージが迷う

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

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

概要と『理由』

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

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

概要を書く理由

概要を書く理由は何か。

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

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

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

理由を書く理由

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

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

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

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

なぜの落とし穴

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

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

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

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

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

○○さんが言ったから、が理由になるときもある

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

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

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

判断どうするか。『それがもしなかったら?』

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

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

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

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

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