なぜ「共通化」を考え、失敗を繰り返すのか

PHP Conference 2025 6/28 Track5

Transcript

1. なぜ「共通化」を考え、失 敗を繰り返すのか PHP Conference 2025 Rinchoku
2. 本トークの位置づけ 話すこと • 「共通化」を行うときのマインドセット • 失敗するときの「臭い」の感覚を養う 話さないこと • 「共通化」のベストプラクティス 備考 • ※本トークはAIを利用してません 2
3. アジェンダ • 自己紹介 • 「共通化」とは • 共通化の失敗例 • 「共通化」で失敗しないための心構え • 最後に 3
4. 自己紹介 名前：Rinchoku 所属：7月に転職 X：@stupid_owl 趣味：宝石鑑賞、ハンドメイド、ジョギング(new) その他 • スタッフ活動 ◦ SRE NEXT 2025 7/11, 12 ◦ オブザーバビリティカンファレンス TOKYO 10/27 ◦ SRE Kaigi 2026コアスタッフ 1/31 • 登壇 ◦ PHP Conference 2024 ◦ PHPer Kaigi 2025 4
5. 「共通化」とは 各機能で共通して現れる処理を、一つの共通処理として実装すること 5 共通処理
6. 「共通化」とは 共通化によって求める効果＝サービスの成長を促すこと • 認知負荷の軽減 • 開発生産性の向上 • バグの減少 • 影響範囲の局所化 • 責任範囲の分離 • etc… 6
7. 「共通化」とは 「共通化」が話題に上がるとき • 「なんか同じような処理を至る所で見るね」 • 「今後運用を考えたときに楽するために」 • 「面倒くさそうだから」 • 「◦◦使って、簡単にできない？」 • 「同じコード資産を流用できるようにしてくれない？」 • etc… 7
8. 「共通化」とは 共通化がうまくいかない＝サービスの成長が鈍る • 可読性の低下 • 認知負荷の増大 • 開発生産性の低下 • 変更時の影響範囲の拡大、不明確性増大 ◦ リリース後にバグが発生 • etc… 8
9. 「共通化」とは Google検索での「共通化」での検索上位(2025/6/16) 1. 共通化とは？ わかりやすく解説 - Weblio辞書 2. 共通化（きょうつうか） とは？ 意味・読み方・使い方 - goo辞書 3. 共通化と標準化を混同せずに使い分けること - IT is my life 4. 標準化と共通化 5. 令和6年度 共通化の対象候補案について 6. コードの共通化による弊害を実感した話 7. 部品共通化 | ビジネス用語集 8. どうしてあなたの共通化は間違っているのか：第1章「単一責任 ... 9. 【第5回】 組織やルールの改革（標準化、共通化） | コラム 10. 共通化(キョウツウカ)とは？ 意味や使い方 9
10. 「共通化」とは Google検索での「共通化」での検索上位(2025/6/16) 1. 共通化とは？ わかりやすく解説 - Weblio辞書 2. 共通化（きょうつうか） とは？ 意味・読み方・使い方 - goo辞書 3. 共通化と標準化を混同せずに使い分けること - IT is my life 4. 標準化と共通化 5. 令和6年度 共通化の対象候補案について 6. コードの共通化による弊害を実感した話 7. 部品共通化 | ビジネス用語集 8. どうしてあなたの共通化は間違っているのか：第 1章「単一責任 ... 9. 【第5回】 組織やルールの改革（標準化、共通化） | コラム 10. 共通化(キョウツウカ)とは？ 意味や使い方 10
11. 「共通化」とは Google検索での「共通化 プログラミング」での検索上位(2025/6/16) 1. コードの共通化について語るときに僕の語ること 2. コードの共通化について数名に聞いてみた #プログラミング 3. 共通化すれば良いとは限らない - Object.create(null) 4. コードを共通化するな 5. 共通化について.md 6. 共通化と標準化を混同せずに使い分けること - IT is my life 7. コードの抽象化および共通化の重要性と実践｜under_the_sky 8. 9年開発を牽引して見えてきた、共通化すべきものと個別で ... 9. コピペコードと共通化とどちらがましか? 10. 【ソースコードの達人】共通化すればいいというものじゃない！な ... 11
12. 「共通化」とは Google検索での「共通化 プログラミング」での検索上位(2025/6/16) 1. コードの共通化について語るときに僕の語ること 2. コードの共通化について数名に聞いてみた #プログラミング 3. 共通化すれば良いとは限らない - Object.create(null) 4. コードを共通化するな 5. 共通化について.md 6. 共通化と標準化を混同せずに使い分けること - IT is my life 7. コードの抽象化および共通化の重要性と実践｜under_the_sky 8. 9年開発を牽引して見えてきた、共通化すべきものと個別で ... 9. コピペコードと共通化とどちらがましか ? 10. 【ソースコードの達人】共通化すればいいというものじゃない！な ... 12
13. 「共通化」とは 世のプログラマーは「共通化」に恨みがある（偏見） 13
14. 「共通化」とは ただし、共通化をしたい！！ 14
15. 共通化の失敗例 • ここからは失敗例 ◦ 似たコード部分をまとめただけ ◦ 既存のクラスに集約 ◦ 引数のArray / Object ◦ やって終わり • 実際に遭遇した、やってしまったものです ※画面サイズの関係で、コードの改行等を調整しています 15
16. 共通化の失敗例：似たコード部分をまとめただけ import { InputHTMLAttributes } from 'react'; interface Props extends InputHTMLAttributes<HTMLInputElement> {label: string;} const Input = ({ label, ...inputHTMLAttributes }: Props) => { return (<label> {['checkbox', 'radio'].includes(inputHTMLAttributes.type ?? 'text') ? ( <><input {...inputHTMLAttributes} /><span>{label}</span></> ) : ( <><span>{label}</span><input {...inputHTMLAttributes} /></> )} </label>);}; export default Input; 16
17. 共通化の失敗例：似たコード部分をまとめただけ import { InputHTMLAttributes } from 'react'; interface Props extends InputHTMLAttributes<HTMLInputElement> {label: string;} const Input = ({ label, ...inputHTMLAttributes }: Props) => { return (<label> {['checkbox', 'radio'].includes(inputHTMLAttributes.type ?? 'text') ? ( <><input {...inputHTMLAttributes} /><span>{label}</span></> ) : ( <><span>{label}</span><input {...inputHTMLAttributes} /></> )} </label>);}; export default Input; 17
18. 共通化の失敗例：似たコード部分をまとめただけ 何がいけないか • 明確にふるまいが変わるものを一つにまとめている ◦ typeで渡す引数が変動 • サポートする値が不明確 ◦ InputHTMLAttributeのため、inputの属性すべてが指定可能 • 自由に引数を渡せるため、影響範囲が不明 • 引数地獄に陥る • etc… 18
19. 共通化の失敗例：似たコード部分をまとめただけ 発生理由 • コードと実際の活用を意識していない • 「自由に設定できる」＝「共通化」という認識 • 「なるべく一つにまとめるのが良い」という認識 19
20. 共通化の失敗例：引数の Array / Object public function getSummary(array $rawData) { $formatted = $this->formatted($rawData); $aggregated = $this->aggregate($formatted); return $aggregated; } 20
21. 共通化の失敗例：引数の Array / Object public function formatted(array $raw): array { $formatted = []; foreach ($raw as $item) { $formatted[$item['userId']][$item['time']][] = [ 'speed' => $item['speed'] / 10, 'calorie' => $item['colorie'], 'time' => $item['time'], ]; } return $formatted; } 21
22. 共通化の失敗例：引数の Array / Object public function aggregate(array $raw): array { $aggregated = []; foreach ($raw as $userItems) { foreach ($userItems as $timeItems) { foreach ($timeItems as $item) { $aggregated['speed'] += $item['speed']; $aggregated['calorie'] += $item['calorie']; } } } return $aggregated; } 22
23. 共通化の失敗例：引数の Array / Object public function formatted(array $raw): array { $formatted = []; foreach ($raw as $item) { $formatted[$item['userId']][$item['time']][] = [ 'speed' => $item['speed'] / 10, 'calorie' => $item['colorie'], 'time' => $item['time'], ]; } return $formatted; } 23
24. 共通化の失敗例：引数の Array / Object 何がいけないか • データ構造を把握しておく必要がある ◦ 利用する/される側どちらでも構造把握が必要 ◦ 複数箇所で利用するには適していない • 型が不安全 • 値がmutable（変更可能） 24
25. 共通化の失敗例：引数の Array / Object 発生理由 • primitiveな型で表現することに慣れている環境 • とりあえず動くコードを書いてみたときに起きやすい • 「色んなデータを扱う＝Array/Objectで柔軟に対応」という考え • Entity/ValueObjectの概念が浸透していない 25
26. 共通化の失敗例：既存のクラスに集約 class ValidateManager { public function isPassword(string $password): bool { ... } public function beforeNow(string $target): bool { ... } } 26
27. 共通化の失敗例：既存のクラスに集約 class ValidateManager { public function isPassword(string $password): bool { ... } public function beforeNow(string $target): bool { ... } } 27
28. 共通化の失敗例：既存のクラスに集約 何がいけないか • 様々なドメイン知識が混在してしまう ◦ 一覧性が低下し、何をしているかわかりづらい • ちょっと似た処理の場合、条件分岐や別関数で記述されやすい • 別の実装者が同じようにコードを同一クラスに書いてしまう可能性 を高める 28
29. 共通化の失敗例：既存のクラスに集約 発生理由 • クラス名の抽象度が高すぎる ◦ 「その中に書こう」という心理を発生させてしまう ◦ 時間が経つほど、依存するファイルも大きくなり変更リスクが上がりやすい • 機能追加・変更で扱う範囲が増大し、とりあえずそれっぽいクラス に書いてしまう 29
30. 共通化の失敗例：やって終わり ◦◦共通化できるのでやります！！ 30
31. 共通化の失敗例：やって終わり ◦◦共通化できるのでやります！！ やりました 31
32. どうでした？ 改善しました？ 共通化の失敗例：やって終わり やりました ◦◦共通化できるのでやります！！ 32
33. 共通化の失敗例：やって終わり 何がいけないか • 想定した通りに使われてるとは限らない ◦ 別の不便が発生してる可能性がある ◦ そもそも使われていない可能性もある • 最初は正しく使われてたが、後の修正などで見るも無残な姿に なってる可能性がある 33
34. 共通化の失敗例：やって終わり 発生理由 • 「自分が不便」＝「他の人も不便」という心理 ◦ 逆に「自分が快適」＝「他の人も快適」と思ってしまう • 「何かあれば言ってくれるだろう」という信頼 ◦ 思っていても言わないことの方が多い ▪ 遠慮、そもそも使えないから放置、忘れたetc… • そこまで工数がかからなかったため、意識に残っていない 34
35. 「共通化」で失敗しないための心構え 「共通化」の言葉に振り回されていないか？ フロー全体を熟知しているか？ どの程度の影響があるか見ているか？ 一気にすべてやろうとしていないか？ トレードオフを考慮しているか？ 相談しているか？ 振り返りをしているか？ 35
36. 「共通化」の言葉に振り回されていないか？ 共通化：各機能で共通して現れる処理を、一つの共通処理として実装 すること weblio辞書https://www.weblio.jp/content/%E5%85%B1%E9%80%9A%E5%8C%96 > 複数の物事のうちどれにも該当・通用するように、変更すること 36
37. 「共通化」の言葉に振り回されていないか？ 「共通化」という言葉だけ見たときの印象 「なんでも受け付けて、よしなにやってくれる」 37
38. 「共通化」の言葉に振り回されていないか？ 「共通化」という言葉だけ見たときの印象 「なんでも受け付けて、よしなにやってくれる」 38 どんなものでも やってくれる印象
39. 「共通化」の言葉に振り回されていないか？ 実際の共通化を行うときに重要なこと ストレスなく、同じものを出力すること ストレスなく • 明示的であること • 余計な情報が存在しないこと • 安定している • テスト容易であること 39
40. 「共通化」の言葉に振り回されていないか？ そのために、一定の制限 を設ける(見つける)ことが重要 • 入力の種類 ◦ 時には値を固定してしまう • 出力の形式 • 適用範囲 • ふるまい • etc… 40
41. フロー全体を熟知しているか？ • 共通化対象の前後でどういうことをするか理解 ◦ なるべくワークフロー図を描けるとよい ◦ 別の方法がよいことが見つかることが多い 41 利用部分 共通化部分 利用部分 活用部分 活用部分 活用部分 活用部分 利用部分 利用部分
42. どの程度の影響があるか見ているか？ 「影響範囲」＝「組織上のどの範囲までか」 • 個人 • チーム • グループ • 会社全体 42
43. どの程度の影響があるか見ているか？ 個人 チーム グループ 会社全体 下に行くほど • 抽象度の増加 • 複雑性の増加 • 関係者の増加 • 求められる機能の増加 • 変更難度の増加 • 求められるリーダーシップ能力の増加 • etc…
44. どの程度の影響があるか見ているか？ よくある話として • 当初「個人向け」と思ったのが、「チーム向け」だった • 「チーム向け」が「会社向け」への変更 対象範囲の認識違い(将来を含む)をなくすことで • 初期から適切な方法の選定 • ステークホルダーとの調整対応の円滑 44
45. 一気にすべてやろうとしていないか？ • 鉄則は「Step by Stepで小さく進める」 ◦ 最近の開発では当たり前になりつつある事象 ◦ 「共通化」では得てして、最終系を最初に求められることが多い • 理由はアジャイル開発と同様のため、割愛 45
46. トレードオフを考慮しているか？ • 方法はなるべく3つ以上考えるのがベスト ◦ メリット、デメリット、期待効果、難易度などをリストアップ ◦ 最初の方法に頭が凝り固まって、よりより方法に気づかないのを防ぐ ▪ 一つぐらいは一風変わった方法を考えるのもよい • 最低限「工数」と「期待効果」で考える ◦ 5人日かかって、年10分程度の削減工数だと割に合わない ◦ 場合によっては、少し泥臭いことを許容する方がメリットが大きくなることもあ る • 「共通化」によって、「変更容易性が下がる」こともある 46
47. 相談しているか？ • 関係者や自分より技術力が高い人（エキスパート）へ相談 ◦ 関係者：フローの認識違い、「実はこういう使い方をしている」の発見 ◦ エキスパート：他によりより手段がないか • 「責任の共有」という観点でも大事 • 相談により相手に頭の片隅に意識させる ことができる ◦ ふとした時に別の方法を見つける ◦ 実際のフローに脇道があったことに気づく 47
48. 振り返りをしているか？ 振り返りをしているか？ • やるだけではただの自己満足 • 利用者が負荷なく、適切に使えている かが大事 • 一つ達成すると、別のやりたいことが増える ◦ やったことはそれにより先延ばしになることも。。。 48
49. 最後に • 共通化の失敗は事前準備が不足してることで起きやすい ◦ 実行に移す前に、一度ちゃんと整理する時間を設ける • 「共通化」という言葉がミスを誘発しやすい ◦ 「フロー化」や「制限化」などの方が実際の流れに則している（気がする） • ちゃんと振り返る機会を定期的に設ける ◦ 最初は最善でも、後に想定外の使われ方をされることもある 49
50. ご清聴 ありがとうございました 50