コミットメッセージを書く時に気をつけていること

コミットメッセージについて、お客さん先で発表した内容になります。

Transcript

1. コミットメッセージを 書く時に気をつけていること 宮田 勉
2. 注意事項 • あくまで一個人の考えです • 正解はありません • 私が普段考えていることの共有です
3. 今日の内容 • コミットメッセージとコミットログ • コミットメッセージのゴール • コミットメッセージを書く上でのポイント紹介 • まとめ
4. 質問です！ こんなコミットメッセージ書いていないですか？ • 実装中 • fix bug • 指摘修正 • リファクタリング • RSpecの修正
5. • 実装中 • fix bug • 指摘修正 • リファクタリング • RSpecの修正 こういうコミットメッセージはよくないと思っています 何が問題だと思っているのかを解説していきます
6. コミットログ 変更履歴（差分、メッセージを含む） 解説の前にまずはコミットについて コミットメッセージ 変更内容の要約 コミットログ コミット メッセージ
7. コミットログについて考える • コミット ◦ 『確約する』『誓約する』 • ログ ◦ 記録 • 直訳すると『確約する記録』
8. 記録の意味についてもう少し考える • 『記録』の意味を辞書で引くと... ◦ 将来のために物事を書きしるしておくこと ◦ 競技などで、数値として表された成績や結果 ◦ 歴史学・古文書学で、史料としての日記や書類
9. 記録の意味についてもう少し考える • 『記録』の意味を辞書で引くと... ◦ 将来のために物事を書きしるしておくこと ◦ 競技などで、数値として表された成績や結果 ◦ 歴史学・古文書学で、史料としての日記や書類 重要そうな言葉が！？
10. 記録をする意味 • 将来のために物事を書き記すということは？ ◦ 後々見直した時に何が起きたかわかるようにするため ◦ 忘れても見れば思い出せるようにするため ◦ 未来でこの物事を見るであろう人にも伝えるため ◦ etc … 自分を含めた未来の人に伝わるようにする必要があります！
11. コミットログも同じ！
12. コミットメッセージ • コミット内容を要約したもの ◦ 修正内容を理解する為に役に立つもの 重要なのは... 読んで何を（What）しているかが伝わること 何を（What）だけでなく、何故（Why）その修正をしたかが伝わること
13. 今回メインになるのはコミットメッセージ • コミットログは、コミットをどう積み方（分け方・まとめ方）の話になる • コミットメッセージは、メッセージをどう書くかの話になる • 今回は、コミットメッセージがメイン（コミットの積み方については深くは 話をしない）
14. 例に戻りましょう コミットメッセージは、以下2点が重要 • 読んで何（What）をしているかが伝わること • 何（What）をだけでなく、何故（Why）その修正をしたかが伝わること 以下コミットメッセージから、修正内容がわかりますか？ • 実装中 • fix bug • 指摘修正 • リファクタリング • RSpecの修正
15. 例に戻りましょう コミットメッセージは、以下2点が重要 • 読んで何（What）をしているかが伝わること • 何（What）をだけでなく、何故（Why）その修正をしたかが伝わること 以下コミットメッセージから、修正内容がわかりますか？ • 実装中 • fix bug • 指摘修正 • リファクタリング • RSpecの修正 何をしているか 伝わらないです
16. 何故伝わらないかを考えてみる • コミット内容（差分）を見ないと何（What）をしているかわからない • 何故（Why）その改修をしたかがわからない コミット内容を見て、1から考える必要が出てくる 何（What）は、最悪差分を見ればわかるが、 何故（Why）は差分から推測しづらい ※ 何故（Why）を書くことが重要 その結果
17. でも、コミットメッセージって見直すことってある？ • あります！ • 例えば... ◦ 案件参画したばかりで、該当システムの仕様の知識が浅い場合、『何でこの処理があるんだ ろう？』って思う時がある ◦ 情報源としては、人、仕様書、コミット ▪ 人：実装者や詳しい人が常にプロジェクトにいる保証はない ▪ 仕様書：メンテされていないリスクやそもそも存在しない場合もある ▪ この場合、コミットメッセージが貴重な情報源になる！ • コミットメッセージに何故（Why）が書かれていないと、実装当時の意図がわか らず、ソースコードから読み取っていくしかない ◦ 時間がかなり取られる！ ◦ 時間をかけても、何故（Why）がわからない可能性もある！
18. 時間を取られない為に意識して欲しいこと • 人間は忘れる生き物です ◦ 今はレビュアーもレビュイーも何でこの実装をしているのかわかるかも知れない ▪ 1週間、1ヶ月後、半年後と経って、改めて見た時に何故（Why）その改修をしたか思 い出せますか？ ▪ 思い出せたとして、すんなり思い出せますか？（思い出し工数かかりませんか？） • 自分一人で開発しているわけではない ◦ チーム開発をしているので、当然他の人も見ます ▪ 自分だけが見ればわかるだと、他の人が見た時に困ります ▪ 差分から何を（What）はわかっても、何故（Why）はコードだけでは推測しづらいも のです
19. コミットメッセージのゴール • コミットメッセージだけで、改修内容が想像つくように書かれている • 何（What）だけでなく、何故（Why）が書かれている あくまで一例ですが、 読んだだけで何となく 改修内容がわかるのが理想
20. 何故（Why）を書くの難しいというあなたへ • 何（What）は書けるけど、何故（Why）を書くのは確かに難しい • 自分も完璧にできている自信はない • 自分が何故（Why）を書く為に意識しているポイントを紹介
21. コミットメッセージの書き方 • ポイントを紹介する前に、一般的な書き方 1. フォーマット a. 1行目 変更内容の要約（必須） b. 2行目 空行 c. 3行目以降 変更した理由（任意） 2. 敬語や丁寧語では書かない a. 命令形推奨ではありますが、日本語の場合は敬語や丁寧語を止めるぐらいで十分 3. 現在形で書く a. 1行目は現在形 b. 3行目以降で経緯を記載する際は過去形でも良い
22. ポイント①：変更が必要になった理由を書く • 何故（Why）を書くとなると、『何故そのコミットをしたのか』を書いてし まうことがある ◦ 例えば ▪ レビューで指摘されたので • 書いて欲しいのは、『何故その変更が必要になったのか』というWhyが必要
23. ポイント②：コミットの粒度 • 何故（Why）が書けない原因として、修正内容が複数混ざっていることがあ る ◦ 差分の大小関係なし
24. ポイント②：コミットの粒度（例） 『機能追加』と『リファクタリング』を1つのコミットにまとめた場合 • どこが機能追加でどこがリファクタリングなのかがわからなくなる ◦ 機能追加とリファクタリングは別物である ▪ 機能追加 → プログラムの動きが変わる ▪ リファクタリング→ プログラムの動きを変えないが、ソースコードを変える 修正内容が異なるので『機能追加』と『リファクタリング』でコミットを分ける
25. コミットの粒度について • コミットの粒度で調べると、人によって様々なやり方があるのであくまで先 ほどのは例です • ここ辺りの記事を参考にしてみたり、他の開発者の話を聞くことをお勧めし ます • 参考記事 ◦ https://qiita.com/jnchito/items/40e0c7d32fde352607be
26. ポイント③：コミットメッセージは1行で書かなくてもよい • 何故（Why）を書こうとすると、1行では説明できないことがある • 改修の経緯を記載すると1行で書くのは厳しい • その場合は3行目以降に経緯を記載する ◦ Slackやチケットのやり取りを載せることもある ▪ ※注意 • URLだと、リンク切れやチケット管理システムの移行で見れなくなることもある 為、リンクのみは避ける
27. ポイント③：コミットメッセージの例 • 1行目 ◦ find_byだとnilを取得して後続処理が進んでしまう為、find_by!に変更 • 3行目以降 ◦ 現状、会員が存在しない場合に、find_byだと、存在しない場合にnilが返ってきて、後続処理 でNoMethodErrorで落ちる ◦ find_by!を使い、存在しない場合はActiveRecord::RecordNotFoundをハンドリングして500エ ラーにならないように修正
28. これらのポイントを押さえると • 差分をみなくても改修内容が想像つく • 何故（Why）が読み取りやすくなる レビューしやすくなる 理解する時間が圧倒的に減る 何故（Why）がわかる その結果
29. まとめ • コミットメッセージには、何（What）だけでなく、何故（Why）も書く • 何故（Why）は変更が必要になった理由を書く • 複数の修正内容を1つのコミットにまとめない • 背景の説明が必要な場合、1行で書かなくても良い
30. コミットメッセージを 上手に活用して、 開発を楽にしていきましょう
31. 紹介 • 今回コミットメッセージの話でした が、開発する上で簡潔にまとまって いる言葉があるので紹介 • https://twitter.com/t_wada/status/9049 16106153828352
32. 参考 • https://qiita.com/konatsu_p/items/dfe199ebe3a7d2010b3e • https://zenn.dev/shotaro/articles/2022-04-20-0000 • https://developers.freee.co.jp/entry/practice-of-git-commit-log • https://www.weblio.jp/ • https://qiita.com/itosho/items/9565c6ad2ffc24c09364 • https://minus9d.hatenablog.com/entry/2014/02/11/125222
33. ご静聴ありがとうございました！