「”誤った使い方をすることが困難”な設計」で良いコードの基礎を固めよう / phpcon-odawara-2025

PHPカンファレンス小田原2025 登壇資料
https://fortee.jp/phpconodawara-2025/proposal/241a237f-4bb7-42fa-989a-d23b6183b2d2

Transcript

1. 「”誤った使い方をすることが 困難”な設計」 taniguhey PHPカンファレンス小田原2025 で 良いコードの基礎を固めよう
2. 自己紹介 ▪ taniguhey / たにぐち ▪ PHP 5年 / Java 1年 ▪ 所属：NE株式会社 - ECの運営支援ツール開発 - BtoBのマーケットプレイス開発 ▪ 特技：オタク特有の早口 ▪ カンファレンス現地初参加・初登壇 X @TanigUhey
3. もくじ • はじめに • サンプルコードを使ったテクニック紹介 ◦ 制約をクラス内部に持たせる ◦ 設計者の意図をコードで伝える • 設計を実践するにあたって • まとめ
4. もくじ • はじめに • サンプルコードを使ったテクニック紹介 ◦ 制約をクラス内部に持たせる ◦ 設計者の意図をコードで伝える • 設計を実践するにあたって • まとめ
5. はじめに ”誤った使い方をすることが困難”とは
6. ”誤った使い方をすることが困難”とは 53. 正しい使い方を簡単に、誤った使い方を困難に 要約すると ソフトウェア開発にはインターフェースを決める タイミングが必ずある。 👎 悪いインターフェースはストレスやミスが増える 👍 良いインターフェースは生産性が上がる https://プログラマが知るべき 97のこと.com/エッセイ/正しい使い方を簡単に、誤った使い方を困難に • 正しく使用する方が操作ミスをするより簡単 • 誤った使い方をすることが困難
7. 「”誤った使い方をすることが困難”な設計」によって... ストレスやミスを減らす • バグを発生させにくくする • チームメンバーの誰でも扱いやすい • 時間が経っても意図を理解しやすい 👎 悪いインターフェース 👍 良いインターフェース
8. この発表の前提や対象 • この発表で扱うインターフェース ◦ 異なる要素同士をつなぐ契約や約束事 ⭕ 自作クラスのメソッドやコンストラクタの引数・戻り値 ❌ ユーザーインターフェース・APIインターフェース ❌ PHPの言語機能としてのInterface
9. この発表の前提や対象 設計する人 あなた ▼ チーム内の開発者 ▼ 使う人 未来のあなた ▼
10. つまりこの発表では あなた が機能を開発する時に使える バグを起こしづらく、チームメンバーに伝わりやすい設計 を メソッドの作り方 ～ クラスの作り方 くらいの話題で テクニックを紹介します。
11. それでは本編始まるのだ
12. もくじ • はじめに • サンプルコードを使ったテクニック紹介 ◦ 制約をクラス内部に持たせる ◦ 設計者の意図をコードで伝える • 設計を実践するにあたって • まとめ
13. サンプルコードの題材 • ECサービスのWebアプリケーション（Amaz◯n・メ◯カリ） ◦ 商品 ▪ 商品名（string：1~20文字） ▪ 価格（int：0~PHP_INT_MAX） ◦ 商品を作成できる ◦ 作成した商品は価格を変更できる ◦ 商品を購入する時、特定の割引率によって割引される
14. サンプルコードの題材 • ECサービスのWebアプリケーション（Amaz◯n・メ◯カリ） ◦ 商品 ▪ 商品名（string：1~20文字） ▪ 価格（int：0~PHP_INT_MAX） ◦ 商品を作成できる ◦ 作成した商品は価格を変更できる ◦ 商品を購入する時、特定の割引率によって割引される
15. 商品作成処理 ありがちな悪い例
16. 商品モデル 商品作成処理 商品作成処理 ありがちな悪い例
17. 商品作成処理 • 何文字のnameが有効か示されていない • priceがマイナスかをチェックしていない 👉 誤りの定義がない ありがちな悪い例
18. バリデーションを追加
19. バリデーションを追加 newする前にバリデーション 👍 めでたしめでたし ではない
20. 誤った使い方を探す 😈誤った使い方 バリデーションを呼び出さずに商品 を新規作成する createProductを使ってくださいと伝 えて回るのだろうか new Productするのは ここだけだろうか
21. テクニック１ 制約をクラス内部に持たせる
22. 制約をクラス内部に持たせる 不自然な値でインスタンス化できないようにコンストラクタを作る 変更においても不完全な状態にならないようにする 実装の中で不完全なインスタンスが存在しないように 作る
23. 制約をクラス内部に持たせる 不自然な値でインスタンス化できないようにコンストラクタを作る 変更においても不完全な状態にならないようにする 実装の中で不完全なインスタンスが存在しないように 作る
24. 制約をコンストラクタに移す
25. コンストラクタに バリデーションを移動 👍 いつどこでnew Productしても 不完全な商品は作れない 制約をコンストラクタに移す
26. サンプルコードの題材（再掲） • ECサービスのWebアプリケーション（Amaz◯n・メ◯カリ） ◦ 商品 ▪ 商品名（string：1~20文字） ▪ 価格（int：0~PHP_INT_MAX） ◦ ユーザーは商品を作成できる ◦ 作成した商品は価格を変更できる ◦ 商品を購入する時、特定の割引率によって割引される
27. 価格の変更処理 ありがちな悪い例
28. 😈誤った使い方 価格のバリデーションを 呼び出さずに価格を変更する 価格の変更処理 ありがちな悪い例 変更したい価格がマイナスでなければ 商品を更新して保存
29. 制約をクラス内部に持たせる（再掲） 不自然な値でインスタンス化できないようにコンストラクタを作る 変更においても不完全な状態にならないようにする 実装の中で不完全なインスタンスが存在しないように 作る
30. 変更処理にも制約を書く
31. クラス内部に持たせる 外部から変更できないように privateにして 変更処理にも制約を書く
32. 👍 いつ変更しても 不完全な商品にならない 変更処理にも制約を書く 途中で変更しても価格は マイナスにできない
33. コンストラクタ 変更 ここまでのまとめ 不完全なインスタンスは作らせない
34. データ バリデーション 同じクラス内に閉じ込める ポイント 誤った使い方をする方が難しい ここまでのまとめ
35. Productクラスの問題点 メソッドの中身を読まないとどんな $price を入れてよいかわからない ❌ そもそも何がOKで何がNGとしている かの意図が伝わりづらい
36. Productクラスの問題点 判定処理が重複している ❌ そもそも何がOKで何がNGとしている かの意図が伝わりづらい ❌ 0円もNGにしたくなったとき、 changePrice()を修正し忘れる誤り メソッドの中身を読まないとどんな $price を入れてよいかわからない
37. 判定処理が重複している ❌ そもそも何がOKで何がNGとしている かの意図が伝わりづらい ❌ 0円もNGにしたくなったとき、 changePrice()を修正し忘れる誤り Productクラスの問題点 メソッドの中身を読まないとどんな $price を入れてよいかわからない
38. テクニック２ 設計者の意図をコードで伝える
39. 設計において意図を伝えるには インターフェース • changePriceを行うには、int型のpriceを与え • changePriceを行った結果として、何も返さない (void) より狭い意味を持つ値をクラスで表現する
40. より狭い意味を持つクラス
41. 商品の価格を表すProductPriceを作る 制約を持たせて マイナスにならないようにする より狭い意味を持つクラス
42. より狭い意味を持つクラス
43. 引数にProductPriceを取るようにする より狭い意味を持つクラス
44. 設計において意図を伝えるには インターフェース（After） • changePriceを行うには、ProductPriceを渡す • changePriceを行った結果として、何も返さない(void)
45. 何が変わったか Before • 成功するかどうかは事前にわからない ◦ 必ず成功させたいならif ($price < 0)判定を呼び出し側にも書かなければならない After • 渡した値がProductPriceであれば必ず変更できる ◦ （少なくとも$priceが原因による失敗はない）
46. ここまでのまとめ
47. ここまでのまとめ コンストラクタも変更 情報量の少ない intやstringは使わない
48. ここまでのまとめ 情報量の少ない intやstringは使わない コンストラクタも変更 判定処理も1箇所だけに
49. 誤った使い方をする方が難しい ここまでのまとめ 使い方がわかるような引数にする ポイント
50. サンプルコードの題材（再掲） • ECサービスのWebアプリケーション（Amaz◯n・メ◯カリ） ◦ 商品 ▪ 商品名（string：1~20文字） ▪ 価格（int：0~PHP_INT_MAX） ◦ ユーザーは商品を作成できる ◦ 作成した商品は価格を変更できる ◦ 商品を購入する時、特定の割引率によって割引される
51. 購入時に割引される処理 割引後の価格を計算 決済システムに送信
52. 設計者の考えを残したい • ◦ 避ける方針にしたい • ◦ 割引が適用されていないProductPriceを受け取れてしまう 他の値と区別するためにクラスを作る
53. 他と区別するためのクラス 中身は一旦ProductPriceと同じ
54. 他と区別するためのクラス
55. 他と区別するためのクラス 割引後の価格が必要だとわかる 使う側は割引後の価格を 用意しなければならなくなった
56. 他と区別するためのクラス
57. 他と区別するためのクラス 割引していない値で newされるかもしれない
58. 他と区別するためのクラス 制約だけでは表せていない
59. 他と区別するためのクラス
60. 他と区別するためのクラス 割引額が何から導き 出されているかを明確にする
61. 他と区別するためのクラス 誤った使い方をする方が難しい 独断で詰め替えることが難しい 割引額が何から導き 出されているかを明確にする
62. 一旦まとめ 割引を計算してから決済す る必要がある... ▲ 使う人
63. 一旦まとめ 割引額を出すには価格と 割引率の両方が必要 ... ▲ 使う人
64. 一旦まとめ ▲ 使う人 何を受け取るか？の候補は たくさんある
65. 一旦まとめ ▲ 使う人 何を受け取るか？の候補は たくさんある 決済サービスには 計算ロジックを 入れたくないようだ...
66. もくじ • はじめに • サンプルコードを使ったテクニック紹介 ◦ 制約をクラス内部に持たせる ◦ 設計者の意図をコードで伝える • 設計を実践するにあたって • まとめ
67. 設計を実践するにあたって Q. 既存コードに適用するには？ 数も多いし影響範囲が広いです。 どれから手をつけていいかわかりません
68. 設計を実践するにあたって Q. 既存コードに適用するには？ 数も多いし影響範囲が広いです。 どれから手をつけていいかわかりません そもそも設計を導入するなら • 当たり前のレベルを上げることを目標に • チーム全体での心理的な変化をもたらす
69. 設計を実践するにあたって Q. 既存コードに適用するには？ 数も多いし影響範囲が広いです。 どれから手をつけていいかわかりません A. 影響範囲が狭く、 仕様をよく理解しているところから テクニックを適用しやすく 慣れてない人でもやりやすい
70. 設計を実践するにあたって • 今日のテクニックをマスターするには ◦ 作る前に使ってみる ▪ テスト駆動開発：テストコードと並行して作る ◦ そのまま実装して誤用されるかを観察 ▪ コードレビューでの修正指摘 ▪ リリース後の不具合
71. 設計を実践するにあたって • もっと深く学びたい人へ ◦ 使わなかった言葉 ▪ フールプルーフ・値オブジェクト・完全コンストラクタ・フェイルファスト・ 契約的プログラミング・表明・ドメインモデル・プリミティブ型執着・ カプセル化・イミュータブル・カプセル化・単一責任・関心の分離・事前条件・ 事後条件・不変条件 ◦ ドンピシャな言葉もあれば、考え方を応用したものもある
72. もくじ • はじめに • サンプルコードを使ったテクニック紹介 ◦ 制約をクラス内部に持たせる ◦ 設計者の意図をコードで伝える • 設計を実践するにあたって • まとめ
73. まとめ • ”誤った使い方をする方が難しい”インターフェースは良いインターフェース ◦ 制約をクラス内部に持たせる ▪ 不自然な値でインスタンス化できないようにコンストラクタを作る ▪ 変更においても不完全な状態にならないようにする ◦ 設計者の意図をコードで伝える ▪ より狭い意味を持つ値をクラスで表現する ▪ 他の値と区別するためにクラスを作る • まずは影響範囲が狭く、仕様をよく理解しているところから始める • 作る前に使う・誤用するか観察する • 基礎が身についたらさらに深い設計へステップアップ
74. ご清聴ありがとうございました 次の発表 taniguhey X @TanigUhey 最近東方ブームが来ています