リーダブルコミットのすゝめ / Recommendation of Readable Commit

2021/05/29 PHPカンファレンス沖縄 2021 でトークした際に使用したスライドです

Transcript

1. 1 © 2012-2021 BASE, Inc. 　　　　2021/05/29 PHPカンファレンス沖縄 2021 @02 リーダブルコミットのすゝめ
2. 2 © 2012-2021 BASE, Inc. 自己紹介 PHPカンファレンス 2019 PHPerのためのテストコード入門 2020 テストピラミッドを意識した テストコード実装戦略 WEB+DB PRESS しっかり，きちんとPHP BankEnd Software Enginner 02 大津 和槻 ：@cocoeyes02 2021/02~ BASE, Inc. Vol.121 Composer 2によるパッケージ管理 初のメジャーバージョンアップで大進化！ Vol.118 PuPHPeteerでE2Eテスト PHP版Puppeteerでお手軽正常系チェック
3. 3 © 2012-2021 BASE, Inc. リーダブルなコミットって何？
4. 4 © 2012-2021 BASE, Inc. リーダブルなコミットって何？ 書き手の意図を 爆速で理解できるコミット
5. 5 © 2012-2021 BASE, Inc. アジェンダ リーダブルなコミットをする理由 １ リーダブルな　　　　　　 コミットメッセージ、内容のtips ２ リーダブルコミットを支える技術 ３
6. 6 © 2012-2021 BASE, Inc. リーダブルなコミットを する理由
7. 7 © 2012-2021 BASE, Inc. 一旦コミット こんなコミットメッセージ見たことありませんか バグを直した PRで指摘されたので反映
8. 8 © 2012-2021 BASE, Inc. 一旦コミット こんなコミットメッセージ見たことありませんか バグを直した PRで指摘されたので反映 コミットは他人が見るものだから、 他人が書き手の意図を理解できないと❌
9. 9 © 2012-2021 BASE, Inc. ・同僚 他人とは？ ・自分 ・コントリビューター
10. 10 © 2012-2021 BASE, Inc. ・同僚 他人とは？ ・自分 ・コントリビューター
11. 11 © 2012-2021 BASE, Inc. ・同僚 他人とは？ ・自分 ・コントリビューター 1.2 読みやすさの定理 > 「他の人」というのは、 > 自分のコードに見覚えのない > ６ヶ月後の「君自身」かもしれない。 過去の自分も未来の自分も、他人である
12. 12 © 2012-2021 BASE, Inc. 書き手の意図がわかるコミットだと どんなメリットがあるか
13. 13 © 2012-2021 BASE, Inc. 書き手の意図がわかるコミットだと どんなメリットがあるか コードを読むだけではわからない 背景がわかる １
14. 14 © 2012-2021 BASE, Inc. コードレビューの負担が減る ２ 書き手の意図がわかるコミットだと どんなメリットがあるか コードを読むだけではわからない 背景がわかる １
15. 15 © 2012-2021 BASE, Inc. コードレビューの負担が減る ２ コードを読むだけではわからない 背景がわかる １ 書き手の意図がわかるコミットだと どんなメリットがあるか 書き手がコードを書いた意図を 忘れても大丈夫 ３
16. 16 © 2012-2021 BASE, Inc. リーダブルなコミット メッセージ、内容のtips
17. 17 © 2012-2021 BASE, Inc. リーダブルなコミットメッセージ、内容のtips プレフィックスをつけよう １ できるだけWhyを書こう ２ コミットメッセージの形を工夫しよう ３
18. 18 © 2012-2021 BASE, Inc. プレフィックスをつけよう feat: ユーザの新規登録機能を実装 fix: ユーザ登録できない不具合があったので、登録バリデーションを修正 chore: 認証ライブラリを追加
19. 19 © 2012-2021 BASE, Inc. プレフィックスをつけよう feat: ユーザの新規登録機能を実装 fix: ユーザ登録できない不具合があったので、登録バリデーションを修正 chore: 認証ライブラリを追加
20. 20 © 2012-2021 BASE, Inc. プレフィックスをつけよう コミットメッセージの先頭につける • feat: 新機能追加 • fix: バグ修正 • docs: ドキュメントのみの変更 • style: コードの意味に影響を及ぼさない変更（空白、フォーマット、 セミコロンの欠落など • refactor: バグの修正も機能の追加も行わないコード変更 • perf: パフォーマンスを向上させるコード変更 • test: 存在しないテストの追加または既存のテストの修正 • chore: ビルドプロセスの変更、またはドキュメント生成などの補助ツールとラ イブラリ feat: ユーザの新規登録機能を実装 fix: ユーザ登録できない不具合があったので、登録バリデーションを修正 chore: 認証ライブラリを追加
21. 21 © 2012-2021 BASE, Inc. プレフィックスをつけよう プレフィックスをつけるとどんな良いことがあるのか？
22. 22 © 2012-2021 BASE, Inc. プレフィックスをつけよう プレフィックスをつけるとどんな良いことがあるのか？ • どんなコミットかある程度わかるので、レビュワーの負担が減る ◦ どんなプレフィックスがあるかレビュワーに共有する必要あり
23. 23 © 2012-2021 BASE, Inc. プレフィックスをつけよう プレフィックスをつけるとどんな良いことがあるのか？ • どんなコミットかある程度わかるので、レビュワーの負担が減る ◦ どんなプレフィックスがあるかレビュワーに共有する必要あり • プレフィックス単位でコミットを分ける習慣がつく ◦ 作業の単位を意識しながらコミットすることができる ◦ 各プレフィックスの粒度もチーム内ですり合わせできると良い
24. 24 © 2012-2021 BASE, Inc. プレフィックスをつけよう プレフィックスをつけるとどんな良いことがあるのか？ • どんなコミットかある程度わかるので、レビュワーの負担が減る ◦ どんなプレフィックスがあるかレビュワーに共有する必要あり • プレフィックス単位でコミットを分ける習慣がつく ◦ 作業の単位を意識しながらコミットすることができる ◦ 各プレフィックスの粒度もチーム内ですり合わせできると良い プレフィックス単体でも効果があるが、 チーム内ですり合わせられるともっと効果を発揮する！
25. 25 © 2012-2021 BASE, Inc. できるだけWhyを書こう
26. 26 © 2012-2021 BASE, Inc. できるだけWhyを書こう コミットから読み取れる情報 • コミット内容 ◦ どのようにコードを変更したか • コミットメッセージ ◦ コードを変更したことで何ができるようになったか ◦ 何故コードを変更したか
27. 27 © 2012-2021 BASE, Inc. できるだけWhyを書こう コミットから読み取れる情報 • コミット内容 → What, How ◦ どのようにコードを変更したか • コミットメッセージ → Why, What ◦ コードを変更したことで何ができるようになったか ◦ 何故コードを変更したか
28. 28 © 2012-2021 BASE, Inc. できるだけWhyを書こう コミットから読み取れる情報 • コミット内容 → What, How ◦ どのようにコードを変更したか • コミットメッセージ → Why, What ◦ コードを変更したことで何ができるようになったか ◦ 何故コードを変更したか ❌ 年齢の引数を追加して購入バリデーションを修正 ⭕ 未成年が20歳以上向け商品を買えてしまう不具合があったので、 　 年齢の引数を追加して購入バリデーションを修正
29. 29 © 2012-2021 BASE, Inc. できるだけWhyを書こう このWhyが上手く書けない時は、 1つのコミットメッセージに複数の作業を含んでいる可能性がある ❌ 様々なバグを直すため、変更 (抽象的すぎる、複数の変更を含んでいる) ⭕ ユーザの新規登録でエラーが発生して登録できないため、　　　　　　　　 新規登録バリデーションを修正
30. 30 © 2012-2021 BASE, Inc. コミットメッセージの形を工夫しよう ex. perf: パフォーマンス向上のため、ユーザ一覧画面のデータ取得ロジック をリファクタリング (空行) DBからデータを取得するロジックでN+1が発生していたので、in句を使う クエリへと修正 (空行) Issue #100
31. 31 © 2012-2021 BASE, Inc. ex. perf: パフォーマンス向上のため、ユーザ一覧画面のデータ取得ロジック をリファクタリング (空行) DBからデータを取得するロジックでN+1が発生していたので、in句を使う クエリへと修正 (空行) Issue #100 タイトル 本文 リンク コミットメッセージの形を工夫しよう
32. 32 © 2012-2021 BASE, Inc. ex. perf: パフォーマンス向上のため、ユーザ一覧画面のデータ取得ロジック をリファクタリング (空行) DBからデータを取得するロジックでN+1が発生していたので、in句を使う クエリへと修正 (空行) Issue #100 コミットメッセージが長くなってしまう場合は、本文を使おう • タイトル部分は50文字以内に納めるとGit公式で推奨（本文も72文字） • コミットメッセージは簡単に書いて、本文に詳細を書く コミットメッセージの形を工夫しよう
33. 33 © 2012-2021 BASE, Inc. ex. perf: パフォーマンス向上のため、ユーザ一覧画面のデータ取得ロジック をリファクタリング (空行) DBからデータを取得するロジックでN+1が発生していたので、in句を使う クエリへと修正 (空行) Issue #100 チケットやissueリンクを貼るのもあり • トラッキングしやすくなる • ビジネス要件的な背景なども追いやすくなる コミットメッセージの形を工夫しよう
34. 34 © 2012-2021 BASE, Inc. リーダブルコミットを 支える技術
35. 35 © 2012-2021 BASE, Inc. Conventional Commits 1.0.0 コミットメッセージの軽量規約 コミットメッセージの形、プレフィックス、複数のルールと強制度が　　 定められている もともとAngularの規約に触発されて生まれた経緯がある他、　　　　　 electronやyargsなどで利用されている
36. 36 © 2012-2021 BASE, Inc. PHP Commitizen Conventional Commitに準拠したコミットメッセージ作成ツール プレフィックスや本文、リンクなど文言を逐次的に入力することでできる composerに依存するPHPプロジェクトに対して設定、使用可能であり、 非PHPプロジェクトに対してもグローバルに使用可能。
37. 37 © 2012-2021 BASE, Inc. 最後に 今回のセッションは自戒が（多分に）含まれています。 とはいえ今回のトークを振り返ると、コミットやコミットメッセージは 書き手と読み手のコミュニケーションだと改めて感じました。 今回のトークが少しでもリーダブルなコミットを書くきっかけになれば 幸いです！
38. 38 © 2012-2021 BASE, Inc. 参考文献 • リーダブルコード――より良いコードを書くためのシンプルで実践的なテクニック https://www.oreilly.co.jp/books/9784873115658/ • 【今日からできる】コミットメッセージに 「プレフィックス」 をつけるだけで、開発効率が上がった話 https://qiita.com/numanomanu/items/45dd285b286a1f7280ed • t_wadaさんのツイート https://twitter.com/t_wada/status/904916106153828352?s=20 • Git - Contributing to a Project https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines • angular.js/DEVELOPERS.md https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#type • Conventional Commits 1.0.0 https://www.conventionalcommits.org/ja/v1.0.0/ • PHP Commitizen https://github.com/conventional-commits/php-commitizen • Working with Git https://slides.com/damianopetrungaro/working-with-git