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