その説明、コードコメントに書く？コミットメッセージに書く？ プルリクエストに書く？ - #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
2. こんなこと、ありませんか？
3. 先輩「この実装はどうしてこうなっているの？」 自分「ここは〇〇という理由でこうしています！」 先輩「了解です、その説明はコードコメントに 書いておくとよいので追記お願いします～」 コードレビューにて......
4. 先輩「この実装はどうしてこうなっているの？」 自分「ここは〇〇という理由でこうしています！」 先輩「了解です、その説明はコードコメントに 書いておくとよいので追記お願いします～」 コードレビューにて...... 🤔 ナンデ？
5. • コードコメント • コミットメッセージ • プルリクエスト（説明欄、コメント） コードの（コードで表現できない）説明を書く場所
6. コードコメント「バグを修正した」 → あとからコードを読む人は変更差分を見ているわけではない 適切な場所を選ばないと......
7. コミットメッセージ「この実装でいいか悩んでいる」 → あとから読んでも「お、おう......」 適切な場所を選ばないと......
8. プルリクエストで「〇〇という理由でこう実装した」 → あとでコードを触るときには目に入らない 適切な場所を選ばないと......
9. 「誰が」「いつ」読むのか？ を考えると 「どんな情報を」書けばいいか？ が分かる！ ポイント
10. • コードコメント • コミットメッセージ • プルリクエスト（説明欄、コメント） コードの（コードで表現できない）説明を書く場所
11. 誰が 将来そのコードをメンテする人（自分含む） いつ 次にそのコードを修正するとき 実装から挙動を読み取るとき コードコメント
12. どんな情報を 「あえてそうしている」こと（後述） → 書かれなかったこと（意図や理由、捨てた実装等）はコードには残らない 次点で認知負荷を下げる説明など（割愛） コードコメント
13. メジャーなライブラリがあるのに自前で実装している ユースケースが特殊で、適切なオプションが提供されていなかった → あとから同じ轍を踏んで時間を無駄にしたりしないよう 「あえてそうしている」ことの例
14. • コードコメント • コミットメッセージ • プルリクエスト（説明欄、コメント） コードの（コードで表現できない）説明を書く場所
15. 誰が 将来そのコードをメンテする人（自分含む） レビュアー いつ 今のコードになった時期や理由を探るとき プルリクエストのレビューをするときにステップごとに見る コミットメッセージ
16. どんな情報を コードの変更の目的、理由 コミットメッセージ
17. 参考資料 https://www.praha-inc.com/lab/posts/commit-message
18. • コードコメント • コミットメッセージ • プルリクエスト（説明欄、コメント） コードの（コードで表現できない）説明を書く場所
19. 誰が レビュアー いつ コードレビュー時 ※本発表ではチーム開発の文脈に限定。 　OSS 等ではソフトウェアの変更に対するドキュメントの役割も持つ。 プルリクエスト（※）
20. どんな情報を プルリクエストの背景説明 • 「〇〇をした際に□□する機能を追加」 • 「××の条件下で△△というバグが発生していたので」 実装全体の説明、相談事項 • 「ここ実装めっちゃ悩んだ（悩んでる）」 • 実装のときに参考にしたドキュメント等 プルリクエスト
21. 「誰が」「いつ」読むのか？ を考えると 「どんな情報を」書けばいいか？ が分かる！ ポイント（再掲）
22. 「誰が」「いつ」読むのか？ を考えると 「どんな情報を」書けばいいか？ が分かる！ ポイント（再掲） 実は、コードの説明だけでなく コミュニケーション全般に言える話 （......という話は別の機会？に）
23. 冒頭で紹介した 3 つのメッセージは それぞれどこに書くべきだったか 考えてみてくださいね！ おまけ
24. 所属：株式会社ウィルゲート 登壇： 寄稿： 岡田 正平／おかしょい Twitter: @okashoi GitHub: @okashoi
26. 補足資料 （LT では話さない）
27. （参考）コードコメント vs. コミットメッセージ コードコメント コミットメッセージ その時点のコードに対する説明 点の情報 コミットに紐づかない 具体寄り コードの変更に対する説明 2 点間をつなぐ線の情報 （変更前後の）コードに結びつく 抽象寄り 辿れる
28. （参考）コミットメッセージ vs. プルリクエスト コミットメッセージ プルリクエスト コードの変更に対する説明 2 点間をつなぐ線の情報 開発者にとって意味がある単位の変更 プルリクエストに紐づかない ソフトウェアの変更に対する説明 複数の点をつなぐ情報 ユーザにとって意味がある単位の変更 複数のコミットに結びつく 具体寄り 抽象寄り 辿れる