その説明、コードコメントに書く？コミットメッセージに書く？ プルリクエストに書く？ - #phpconfuk 2023

2023/06/24 開催「PHPカンファレンス福岡2023」（https://phpcon.fukuoka.jp/2023/ ）の LT 資料です。

詳細：https://fortee.jp/phpconfukuoka-2023/proposal/ae71f3a7-4c3c-4c87-8816-8426bcc8d325

Transcript

1. その説明、コードコメントに書く？
   コミットメッセージに書く？
   プルリクエストに書く？
   2023/06/24 PHPカンファレンス福岡 2023
   @okashoi
   

   View Slide

2. こんなこと、ありませんか？
   

   View Slide

3. 先輩「この実装はどうしてこうなっているの？」
   自分「ここは〇〇という理由でこうしています！」
   先輩「了解です、その説明はコードコメントに
   書いておくとよいので追記お願いします～」
   コードレビューにて......
   

   View Slide

4. 先輩「この実装はどうしてこうなっているの？」
   自分「ここは〇〇という理由でこうしています！」
   先輩「了解です、その説明はコードコメントに
   書いておくとよいので追記お願いします～」
   コードレビューにて......
   🤔
   ナンデ？
   

   View Slide

5. • コードコメント
   • コミットメッセージ
   • プルリクエスト（説明欄、コメント）
   コードの（コードで表現できない）説明を書く場所
   

   View Slide

6. コードコメント「バグを修正した」
   → あとからコードを読む人は変更差分を見ているわけではない
   適切な場所を選ばないと......
   

   View Slide

7. コミットメッセージ「この実装でいいか悩んでいる」
   → あとから読んでも「お、おう......」
   適切な場所を選ばないと......
   

   View Slide

8. プルリクエストで「〇〇という理由でこう実装した」
   → あとでコードを触るときには目に入らない
   適切な場所を選ばないと......
   

   View Slide

9. 「誰が」「いつ」読むのか？
   を考えると
   「どんな情報を」書けばいいか？
   が分かる！
   ポイント
   

   View Slide

10. • コードコメント
    • コミットメッセージ
    • プルリクエスト（説明欄、コメント）
    コードの（コードで表現できない）説明を書く場所
    

    View Slide

11. 誰が
    将来そのコードをメンテする人（自分含む）
    いつ
    次にそのコードを修正するとき
    実装から挙動を読み取るとき
    コードコメント
    

    View Slide

12. どんな情報を
    「あえてそうしている」こと（後述）
    → 書かれなかったこと（意図や理由、捨てた実装等）はコードには残らない
    次点で認知負荷を下げる説明など（割愛）
    コードコメント
    

    View Slide

13. メジャーなライブラリがあるのに自前で実装している
    ユースケースが特殊で、適切なオプションが提供されていなかった
    → あとから同じ轍を踏んで時間を無駄にしたりしないよう
    「あえてそうしている」ことの例
    

    View Slide

14. • コードコメント
    • コミットメッセージ
    • プルリクエスト（説明欄、コメント）
    コードの（コードで表現できない）説明を書く場所
    

    View Slide

15. 誰が
    将来そのコードをメンテする人（自分含む）
    レビュアー
    いつ
    今のコードになった時期や理由を探るとき
    プルリクエストのレビューをするときにステップごとに見る
    コミットメッセージ
    

    View Slide

16. どんな情報を
    コードの変更の目的、理由
    コミットメッセージ
    

    View Slide

17. 参考資料
    https://www.praha-inc.com/lab/posts/commit-message
    

    View Slide

18. • コードコメント
    • コミットメッセージ
    • プルリクエスト（説明欄、コメント）
    コードの（コードで表現できない）説明を書く場所
    

    View Slide

19. 誰が
    レビュアー
    いつ
    コードレビュー時
    ※本発表ではチーム開発の文脈に限定。
    　OSS 等ではソフトウェアの変更に対するドキュメントの役割も持つ。
    プルリクエスト（※）
    

    View Slide

20. どんな情報を
    プルリクエストの背景説明
    • 「〇〇をした際に□□する機能を追加」
    • 「××の条件下で△△というバグが発生していたので」
    実装全体の説明、相談事項
    • 「ここ実装めっちゃ悩んだ（悩んでる）」
    • 実装のときに参考にしたドキュメント等
    プルリクエスト
    

    View Slide

21. 「誰が」「いつ」読むのか？
    を考えると
    「どんな情報を」書けばいいか？
    が分かる！
    ポイント（再掲）
    

    View Slide

22. 「誰が」「いつ」読むのか？
    を考えると
    「どんな情報を」書けばいいか？
    が分かる！
    ポイント（再掲）
    実は、コードの説明だけでなく
    コミュニケーション全般に言える話
    （......という話は別の機会？に）
    

    View Slide

23. 冒頭で紹介した 3 つのメッセージは
    それぞれどこに書くべきだったか
    考えてみてくださいね！
    おまけ
    

    View Slide

24. 所属：株式会社ウィルゲート
    登壇：
    寄稿：
    岡田 正平／おかしょい
    Twitter: @okashoi
    GitHub: @okashoi
    

    View Slide

25. View Slide

26. 補足資料
    （LT では話さない）
    

    View Slide

27. （参考）コードコメント vs. コミットメッセージ
    コードコメント コミットメッセージ
    その時点のコードに対する説明
    点の情報
    コミットに紐づかない
    具体寄り
    コードの変更に対する説明
    2 点間をつなぐ線の情報
    （変更前後の）コードに結びつく
    抽象寄り
    辿れる
    

    View Slide

28. （参考）コミットメッセージ vs. プルリクエスト
    コミットメッセージ プルリクエスト
    コードの変更に対する説明
    2 点間をつなぐ線の情報
    開発者にとって意味がある単位の変更
    プルリクエストに紐づかない
    ソフトウェアの変更に対する説明
    複数の点をつなぐ情報
    ユーザにとって意味がある単位の変更
    複数のコミットに結びつく
    具体寄り 抽象寄り
    辿れる
    

    View Slide