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

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

02
May 29, 2021

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

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

02

May 29, 2021
Tweet

More Decks by 02

Other Decks in Programming

Transcript

  1. 1
    © 2012-2021 BASE, Inc.
        2021/05/29 PHPカンファレンス沖縄 2021
    @02
    リーダブルコミットのすゝめ

    View Slide

  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でお手軽正常系チェック

    View Slide

  3. 3
    © 2012-2021 BASE, Inc.
    リーダブルなコミットって何?

    View Slide

  4. 4
    © 2012-2021 BASE, Inc.
    リーダブルなコミットって何?
    書き手の意図を
    爆速で理解できるコミット

    View Slide

  5. 5
    © 2012-2021 BASE, Inc.
    アジェンダ
    リーダブルなコミットをする理由

    リーダブルな      
    コミットメッセージ、内容のtips

    リーダブルコミットを支える技術

    View Slide

  6. 6
    © 2012-2021 BASE, Inc.
    リーダブルなコミットを
    する理由

    View Slide

  7. 7
    © 2012-2021 BASE, Inc.
    一旦コミット
    こんなコミットメッセージ見たことありませんか
    バグを直した
    PRで指摘されたので反映

    View Slide

  8. 8
    © 2012-2021 BASE, Inc.
    一旦コミット
    こんなコミットメッセージ見たことありませんか
    バグを直した
    PRで指摘されたので反映
    コミットは他人が見るものだから、
    他人が書き手の意図を理解できないと❌

    View Slide

  9. 9
    © 2012-2021 BASE, Inc.
    ・同僚
    他人とは?
    ・自分
    ・コントリビューター

    View Slide

  10. 10
    © 2012-2021 BASE, Inc.
    ・同僚
    他人とは?
    ・自分
    ・コントリビューター

    View Slide

  11. 11
    © 2012-2021 BASE, Inc.
    ・同僚
    他人とは?
    ・自分
    ・コントリビューター
    1.2 読みやすさの定理
    > 「他の人」というのは、
    > 自分のコードに見覚えのない
    > 6ヶ月後の「君自身」かもしれない。
    過去の自分も未来の自分も、他人である

    View Slide

  12. 12
    © 2012-2021 BASE, Inc.
    書き手の意図がわかるコミットだと
    どんなメリットがあるか

    View Slide

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

    View Slide

  14. 14
    © 2012-2021 BASE, Inc.
    コードレビューの負担が減る

    書き手の意図がわかるコミットだと
    どんなメリットがあるか
    コードを読むだけではわからない
    背景がわかる

    View Slide

  15. 15
    © 2012-2021 BASE, Inc.
    コードレビューの負担が減る

    コードを読むだけではわからない
    背景がわかる

    書き手の意図がわかるコミットだと
    どんなメリットがあるか
    書き手がコードを書いた意図を
    忘れても大丈夫

    View Slide

  16. 16
    © 2012-2021 BASE, Inc.
    リーダブルなコミット
    メッセージ、内容のtips

    View Slide

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

    できるだけWhyを書こう

    コミットメッセージの形を工夫しよう

    View Slide

  18. 18
    © 2012-2021 BASE, Inc.
    プレフィックスをつけよう
    feat: ユーザの新規登録機能を実装
    fix: ユーザ登録できない不具合があったので、登録バリデーションを修正
    chore: 認証ライブラリを追加

    View Slide

  19. 19
    © 2012-2021 BASE, Inc.
    プレフィックスをつけよう
    feat: ユーザの新規登録機能を実装
    fix: ユーザ登録できない不具合があったので、登録バリデーションを修正
    chore: 認証ライブラリを追加

    View Slide

  20. 20
    © 2012-2021 BASE, Inc.
    プレフィックスをつけよう
    コミットメッセージの先頭につける
    ● feat: 新機能追加
    ● fix: バグ修正
    ● docs: ドキュメントのみの変更
    ● style: コードの意味に影響を及ぼさない変更(空白、フォーマット、
    セミコロンの欠落など
    ● refactor: バグの修正も機能の追加も行わないコード変更
    ● perf: パフォーマンスを向上させるコード変更
    ● test: 存在しないテストの追加または既存のテストの修正
    ● chore: ビルドプロセスの変更、またはドキュメント生成などの補助ツールとラ
    イブラリ
    feat: ユーザの新規登録機能を実装
    fix: ユーザ登録できない不具合があったので、登録バリデーションを修正
    chore: 認証ライブラリを追加

    View Slide

  21. 21
    © 2012-2021 BASE, Inc.
    プレフィックスをつけよう
    プレフィックスをつけるとどんな良いことがあるのか?

    View Slide

  22. 22
    © 2012-2021 BASE, Inc.
    プレフィックスをつけよう
    プレフィックスをつけるとどんな良いことがあるのか?
    ● どんなコミットかある程度わかるので、レビュワーの負担が減る
    ○ どんなプレフィックスがあるかレビュワーに共有する必要あり

    View Slide

  23. 23
    © 2012-2021 BASE, Inc.
    プレフィックスをつけよう
    プレフィックスをつけるとどんな良いことがあるのか?
    ● どんなコミットかある程度わかるので、レビュワーの負担が減る
    ○ どんなプレフィックスがあるかレビュワーに共有する必要あり
    ● プレフィックス単位でコミットを分ける習慣がつく
    ○ 作業の単位を意識しながらコミットすることができる
    ○ 各プレフィックスの粒度もチーム内ですり合わせできると良い

    View Slide

  24. 24
    © 2012-2021 BASE, Inc.
    プレフィックスをつけよう
    プレフィックスをつけるとどんな良いことがあるのか?
    ● どんなコミットかある程度わかるので、レビュワーの負担が減る
    ○ どんなプレフィックスがあるかレビュワーに共有する必要あり
    ● プレフィックス単位でコミットを分ける習慣がつく
    ○ 作業の単位を意識しながらコミットすることができる
    ○ 各プレフィックスの粒度もチーム内ですり合わせできると良い
    プレフィックス単体でも効果があるが、
    チーム内ですり合わせられるともっと効果を発揮する!

    View Slide

  25. 25
    © 2012-2021 BASE, Inc.
    できるだけWhyを書こう

    View Slide

  26. 26
    © 2012-2021 BASE, Inc.
    できるだけWhyを書こう
    コミットから読み取れる情報
    ● コミット内容
    ○ どのようにコードを変更したか
    ● コミットメッセージ
    ○ コードを変更したことで何ができるようになったか
    ○ 何故コードを変更したか

    View Slide

  27. 27
    © 2012-2021 BASE, Inc.
    できるだけWhyを書こう
    コミットから読み取れる情報
    ● コミット内容 → What, How
    ○ どのようにコードを変更したか
    ● コミットメッセージ → Why, What
    ○ コードを変更したことで何ができるようになったか
    ○ 何故コードを変更したか

    View Slide

  28. 28
    © 2012-2021 BASE, Inc.
    できるだけWhyを書こう
    コミットから読み取れる情報
    ● コミット内容 → What, How
    ○ どのようにコードを変更したか
    ● コミットメッセージ → Why, What
    ○ コードを変更したことで何ができるようになったか
    ○ 何故コードを変更したか
    ❌ 年齢の引数を追加して購入バリデーションを修正
    ⭕ 未成年が20歳以上向け商品を買えてしまう不具合があったので、  
    年齢の引数を追加して購入バリデーションを修正

    View Slide

  29. 29
    © 2012-2021 BASE, Inc.
    できるだけWhyを書こう
    このWhyが上手く書けない時は、
    1つのコミットメッセージに複数の作業を含んでいる可能性がある
    ❌ 様々なバグを直すため、変更 (抽象的すぎる、複数の変更を含んでいる)
    ⭕ ユーザの新規登録でエラーが発生して登録できないため、        
    新規登録バリデーションを修正

    View Slide

  30. 30
    © 2012-2021 BASE, Inc.
    コミットメッセージの形を工夫しよう
    ex.
    perf: パフォーマンス向上のため、ユーザ一覧画面のデータ取得ロジック
    をリファクタリング
    (空行)
    DBからデータを取得するロジックでN+1が発生していたので、in句を使う
    クエリへと修正
    (空行)
    Issue #100

    View Slide

  31. 31
    © 2012-2021 BASE, Inc.
    ex.
    perf: パフォーマンス向上のため、ユーザ一覧画面のデータ取得ロジック
    をリファクタリング
    (空行)
    DBからデータを取得するロジックでN+1が発生していたので、in句を使う
    クエリへと修正
    (空行)
    Issue #100
    タイトル
    本文
    リンク
    コミットメッセージの形を工夫しよう

    View Slide

  32. 32
    © 2012-2021 BASE, Inc.
    ex.
    perf: パフォーマンス向上のため、ユーザ一覧画面のデータ取得ロジック
    をリファクタリング
    (空行)
    DBからデータを取得するロジックでN+1が発生していたので、in句を使う
    クエリへと修正
    (空行)
    Issue #100
    コミットメッセージが長くなってしまう場合は、本文を使おう
    ● タイトル部分は50文字以内に納めるとGit公式で推奨(本文も72文字)
    ● コミットメッセージは簡単に書いて、本文に詳細を書く
    コミットメッセージの形を工夫しよう

    View Slide

  33. 33
    © 2012-2021 BASE, Inc.
    ex.
    perf: パフォーマンス向上のため、ユーザ一覧画面のデータ取得ロジック
    をリファクタリング
    (空行)
    DBからデータを取得するロジックでN+1が発生していたので、in句を使う
    クエリへと修正
    (空行)
    Issue #100
    チケットやissueリンクを貼るのもあり
    ● トラッキングしやすくなる
    ● ビジネス要件的な背景なども追いやすくなる
    コミットメッセージの形を工夫しよう

    View Slide

  34. 34
    © 2012-2021 BASE, Inc.
    リーダブルコミットを
    支える技術

    View Slide

  35. 35
    © 2012-2021 BASE, Inc.
    Conventional Commits 1.0.0
    コミットメッセージの軽量規約
    コミットメッセージの形、プレフィックス、複数のルールと強制度が  
    定められている
    もともとAngularの規約に触発されて生まれた経緯がある他、     
    electronやyargsなどで利用されている

    View Slide

  36. 36
    © 2012-2021 BASE, Inc.
    PHP Commitizen
    Conventional Commitに準拠したコミットメッセージ作成ツール
    プレフィックスや本文、リンクなど文言を逐次的に入力することでできる
    composerに依存するPHPプロジェクトに対して設定、使用可能であり、
    非PHPプロジェクトに対してもグローバルに使用可能。

    View Slide

  37. 37
    © 2012-2021 BASE, Inc.
    最後に
    今回のセッションは自戒が(多分に)含まれています。
    とはいえ今回のトークを振り返ると、コミットやコミットメッセージは
    書き手と読み手のコミュニケーションだと改めて感じました。
    今回のトークが少しでもリーダブルなコミットを書くきっかけになれば
    幸いです!

    View Slide

  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

    View Slide