Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

De4cef85165e8a063b5e40fe1f24daa4?s=47 02
May 29, 2021

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

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

De4cef85165e8a063b5e40fe1f24daa4?s=128

02

May 29, 2021
Tweet

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. アジェンダ リーダブルなコミットをする理由 1 リーダブルな       コミットメッセージ、内容のtips

    2 リーダブルコミットを支える技術 3
  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

    読みやすさの定理 > 「他の人」というのは、 > 自分のコードに見覚えのない > 6ヶ月後の「君自身」かもしれない。 過去の自分も未来の自分も、他人である
  12. 12 © 2012-2021 BASE, Inc. 書き手の意図がわかるコミットだと どんなメリットがあるか

  13. 13 © 2012-2021 BASE, Inc. 書き手の意図がわかるコミットだと どんなメリットがあるか コードを読むだけではわからない 背景がわかる 1

  14. 14 © 2012-2021 BASE, Inc. コードレビューの負担が減る 2 書き手の意図がわかるコミットだと どんなメリットがあるか コードを読むだけではわからない

    背景がわかる 1
  15. 15 © 2012-2021 BASE, Inc. コードレビューの負担が減る 2 コードを読むだけではわからない 背景がわかる 1

    書き手の意図がわかるコミットだと どんなメリットがあるか 書き手がコードを書いた意図を 忘れても大丈夫 3
  16. 16 © 2012-2021 BASE, Inc. リーダブルなコミット メッセージ、内容のtips

  17. 17 © 2012-2021 BASE, Inc. リーダブルなコミットメッセージ、内容のtips プレフィックスをつけよう 1 できるだけWhyを書こう 2

    コミットメッセージの形を工夫しよう 3
  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