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