Upgrade to Pro — share decks privately, control downloads, hide ads and more …

PHPカンファレンス名古屋-テックリードの経験から学んだ設計の教訓

HayatoKudou
February 21, 2025

 PHPカンファレンス名古屋-テックリードの経験から学んだ設計の教訓

HayatoKudou

February 21, 2025
Tweet

More Decks by HayatoKudou

Other Decks in Technology

Transcript

  1. ©︎tete marche CO., LTD. 2 工藤 颯斗(クドウ ハヤト) @metalic_kudo_h ▪

    所属 テテマーチ株式会社 ▪ プロダクト SINIS for Instagram ▪ 職業 Webアプリケーションエンジニア ▪ 趣味 天体観測・魚を捌くこと
  2. ©︎tete marche CO., LTD. Index 目次 5 1. ドキュメント設計 ・ADRもっとはやく導入すればよかった

    2. テスト戦略 ・アイスクリームコーン型の放置をしなければよかった ・カバレッジ率を計測すればよかった 3. 移行戦略 ・ストラングラーパターンに沿って進めればよかった
  3. ©︎tete marche CO., LTD. 8 ドキュメントを作る際のルールがなく 好きな場所に好きなフォーマットで運用していた ドキュメント運用の問題点 • 議事録のようなフロー型の情報と、設

    計ドキュメントのようなストック型の 情報が混在していた • エンジニア用の情報とビジネス用の情 報も混在していた • フォーマットが統一されていない etc…
  4. ©︎tete marche CO., LTD. 13 フェーズが進むごとに実害がでてきた問題 • どこに情報があるのかわからない • 信用できる情報かわからない

    • 同じ内容の議論が何度も蒸し返される • 後から振り返りができない ドキュメントが散在しているため 欲しい情報の格納先がわからない
  5. ©︎tete marche CO., LTD. 14 フェーズが進むごとに実害がでてきた問題 • どこに情報があるのかわからない • 信用できる情報かわからない

    • 同じ内容の議論が何度も蒸し返される • 後から振り返りができない ドキュメントがメンテナンスされている保証が ないので古い情報の可能性がある
  6. ©︎tete marche CO., LTD. 15 フェーズが進むごとに実害がでてきた問題 • どこに情報があるのかわからない • 信用できる情報かわからない

    • 同じ内容の議論が何度も蒸し返される • 後から振り返りができない コードレビューで一度議論した内容を忘れて、 また別の人と同じ議論をしたり、時間が経って から同じ内容の議論をしたり
  7. ©︎tete marche CO., LTD. 16 フェーズが進むごとに実害がでてきた問題 • どこに情報があるのかわからない • 信用できる情報かわからない

    • 同じ内容の議論が何度も蒸し返される • 後から振り返りができない 外部のライブラリをいれる際に、 ・当時どのような制約や要件があって ・競合ライブラリはどういう状態で ・どういう判断からそのライブラリを選定した みたいな意思決定の背景が残っておらず、当時と状況 が変わった際に動けない
  8. ©︎tete marche CO., LTD. 17 後から振り返りができないことでの問題 状況の変化に対応できない • 世の中の技術もプロダクトの状況も変化するし、自身やチームの知識や経験も日々変化する •

    現在の状況に基づいて最適な選択肢を検討しようとしても、過去の意思決定がどのような理 由で行われたのかが不明なため、変更の影響範囲やリスクを正確に把握できない なんでこんな設計に したんだっけ? 忘れた …
  9. ©︎tete marche CO., LTD. 18 後から振り返りができないことでの問題 状況の変化に対応できない • 世の中の技術もプロダクトの状況も変化するし、自身やチームの知識や経験も日々変化する •

    現在の状況に基づいて最適な選択肢を検討しようとしても、過去の意思決定がどのような理 由で行われたのかが不明なため、変更の影響範囲やリスクを正確に把握できない なんでこんな設計に したんだっけ? 忘れた じゃあいっか… 現状維持の選択を取りがちになっていた
  10. ©︎tete marche CO., LTD. 21 ADRとは? ADRとはArchitecture Decision Record の略称で

    直訳すると「アーキテクチャ決定記録」 • Architecture = アーキテクチャ • Decision = 決定 • Record = 記録 Action-Domain-Responder ではないよ
  11. ©︎tete marche CO., LTD. 23 ADRの目的 なぜアーキテクチャの決定記録を残す必要があるのか? こういう事態になることを防ぎたい • 過去の意思決定した状況とは大きく変わっているのに見直しがされない

    • 「ここの設計どうしてこうなってたんだっけ?」が発生してしまう • 同じ内容の議論が何度も蒸し返される • 議論の内容が曖昧で何が意思決定されたのかわかりにくい
  12. ©︎tete marche CO., LTD. 24 ADRフロー 1. オーナーなど関係なく、作ったほうが良い と考えた人がテンプレートを元にADRを作 成する

    2. ADRが作られたらそのプロダクトの開発メ ンバー全員でレビューする 3. 全員の承認を受けたらAccepted、非承認 の場合はRejectedにする 4. 承認されたADRの内容を後から変更する場 合は、新規にADRを作成し、既存ADRは Deprecatedにする
  13. ©︎tete marche CO., LTD. 25 ADRフロー 1. オーナーなど関係なく、作ったほうが良い と考えた人がテンプレートを元にADRを作 成する

    2. ADRが作られたらそのプロダクトの開発メ ンバー全員でレビューする 3. 全員の承認を受けたらAccepted、非承認 の場合はRejectedにする 4. 承認されたADRの内容を後から変更する場 合は、新規にADRを作成し、既存ADRは Deprecatedにする (メンバー規模によるが) 全員参加がオススメ 設計の合意形成を取りつつ、集合知を初動で結集できる
  14. ©︎tete marche CO., LTD. 26 ADR格納場所 ▪ 必須要件 • 開発メンバー全員が閲覧できること

    • リンクが作れること • Slack連携ができること • コメント機能があること ▪ 希望要件 • ADRフォーマットのテンプレート化ができること • 使い馴染みがあること • コメント機能が充実していること
  15. ©︎tete marche CO., LTD. ▪ 必須要件 • 開発メンバー全員が閲覧できること • リンクが作れること

    • Slack連携ができること • コメント機能があること ▪ 希望要件 • ADRフォーマットのテンプレート化ができること • 使い馴染みがあること • コメント機能が充実していること 27 ADR格納場所 コードレビュー等での 参照先にできるように
  16. ©︎tete marche CO., LTD. 30 要件を満たした格納場所候補 • Notion ← レビュープロセスが難しい

    • GitHub • Issues ← 問題についてのみ扱いたい • Repository ← ソースコードについてのみ扱いたい • Discussions ← 採用
  17. ©︎tete marche CO., LTD. 31 要件を満たした格納場所候補 • Notion • GitHub

    • Issues • Repository • Discussions 完全に好みなので チームに合うツール選定で大丈夫
  18. ©︎tete marche CO., LTD. 32 ADRフォーマット • Title (〇〇についてのような体言止めにせず、〇〇にするみたいな文にする) •

    Status (ADRが承認中なのか等のステータス) • Context (決定が必要となった背後にある動機や理由) • Material for decision (決定時に参照した材料) • Decision (最終的な決定内容と理由)
  19. ©︎tete marche CO., LTD. 41 ADR運用の感想 Good • 設計の意思決定に関するドキュメントが散在しなくなった •

    同じ内容の議論が何度も蒸し返されなくなった • 後から振り返りができるようになった • 全員が設計の議論に関わるので合意形成を取りながら設計できるように なった More • アーキテクチャ設計以外のドキュメントは以前と問題が残ったまま • プロダクト初期フェーズに意思決定した内容がADR化されておらず、古い ドキュメントが混乱の元になっている
  20. ©︎tete marche CO., LTD. アイスクリームコーン型テストとは? 47 • 自動テストを「ユニットテスト、インテグレーション テスト、E2Eテスト」の3つの階層で考えた際、下に 階層に行くほど、テストケース数が多いのが望ましい

    • アイスクリームコーン型は、その逆のアンチパターン で「上の階層に行くほどテストケースが多い」という 比率を示している フロントエンドが 手動テストに頼りすぎていた
  21. ©︎tete marche CO., LTD. アイスクリームコーン型テストの問題は 49 短期的には問題がなくても、機能に変更が入る度に手動 でテストをする必要があり、テストにかかるコストが増 大していく •

    頻繁なリリースが必要なほど、手動テスト をする回数が増えるのでコストが高くなる (弊社は毎週リリースしているので大変) • 手動テストに時間がかかり開発が遅れる
  22. ©︎tete marche CO., LTD. 教訓 56 後からテストを整備する困難さ • テストはビジネス成果が見えにくく、リソース確保が後回しに なりがち

    • 手動テストだけで進めた場合、それが基準になってしまい、自 動テスト導入を「開発コスト増」と見なされる恐れがある • 初期フェーズのアイスクリームコーン型テストの理由や背景を ステークホルダーとしっかり共有することが、ピラミッド型移 行時のリソース確保において必要だった
  23. ©︎tete marche CO., LTD. テストカバレッジとは? 58 テストがソースコードのどの程度を網羅しているかを示す指標 主に以下の網羅基準で評価する • 命令網羅

    (statement coverage) (C0) • 分岐網羅 (branch coverage) (C1) • 条件網羅 (condition coverage) (C2) • 経路網羅 (Path Coverage) (PC)
  24. ©︎tete marche CO., LTD. テストカバレッジをなぜ計測しなかった? 59 テストカバレッジへの理解不足 • コードの書き方によってテストカバレッジは変わるらしい? •

    テストカバレッジが高いからと言って、良いテストとは限らない? • テストカバレッジを100%にしても、バグ検出できないパターンがある らしい?
  25. ©︎tete marche CO., LTD. テストカバレッジをなぜ計測しなかった? 60 テストカバレッジへの理解不足 • コードの書き方によってテストカバレッジは変わるらしい? •

    テストカバレッジが高いからと言って、良いテストとは限らない? • テストカバレッジを100%にしても、バグ検出できないパターンがある らしい? テストカバレッジ = 信頼性の低い定量データ と考えた結果、必要性を感じなかった
  26. ©︎tete marche CO., LTD. どういうテスト戦略にしていた? 61 ▪フロントエンド • リリースタイミングでの受け入れテスト •

    重要なロジック・複雑なロジックのみ自動テスト化 ▪ バックエンド • ユースケースに基づいたテストケースを自動化
  27. ©︎tete marche CO., LTD. どういうテスト戦略にしていた? 62 ▪フロントエンド • リリースタイミングでの受け入れテスト •

    重要なロジック・複雑なロジックのみ自動テスト化 → アイスクリームコーン型になっているためカバレッジは低い ▪ バックエンド • ユースケースに基づいたテストケースを自動化 → ユースケースを網羅しているしカバレッジも高いだろう
  28. ©︎tete marche CO., LTD. テストカバレッジの目安は? 68 GoogleのCode Coverage Best Practices

    を参照 • 「理想的なコード カバレッジの数値」というものはない • 60% を「許容範囲」 • 75% を「推奨範囲」 • 90% を「模範的」 引用: https://testing.googleblog.com/2020/08/code-coverage-best-practices.html
  29. ©︎tete marche CO., LTD. テストカバレッジの目安は? 69 GoogleのCode Coverage Best Practices

    を参照 • 「理想的なコード カバレッジの数値」というものはない • 60% を「許容範囲」 • 75% を「推奨範囲」 • 90% を「模範的」 引用: https://testing.googleblog.com/2020/08/code-coverage-best-practices.html うわっ・・・我々のテストカバレッジ、 低すぎ・・・?
  30. ©︎tete marche CO., LTD. 教訓 70 テストコードが存在しているだけで安心せず、実際にどの 程度を網羅しているのか把握しておく必要がある • テストカバレッジの数値だけでは「良いテストかどうか」を完全には判断で

    きないが、十分に網羅されていなければテストの質が低いと判断できる • 後からカバレッジ不足に気づいてテストを充実させようとしても、時間やリ ソースの確保が困難になる • 初期段階からテストカバレッジを測定し、目標値を設定してテスト戦略を充 実させるべきだった
  31. ©︎tete marche CO., LTD. 教訓 71 テストを書いていないと、テストをしにくい設計になってい ることに気が付けない • クラス内で直接依存オブジェクトを生成したり、静的メソッドを多用したりす

    ると、システムが密結合になり、モックへの差し替えが難しくなる • テストを書くことで、こうした設計上の問題に気づき、改善の機会を得られる • テストを書かないことは設計自体の改善の機会を逃すリスクにつながる
  32. ©︎tete marche CO., LTD. テストを書いていないと、テストをしにくい設計になってい ることに気が付けない • クラス内で直接依存オブジェクトを生成したり、静的メソッドを多用したりす ると、システムが密結合になり、モックへの差し替えが難しくなる •

    テストを書くことで、こうした設計上の問題に気づき、改善の機会を得られる • テストを書かないことは設計自体の改善の機会を逃すリスクにつながる 教訓 72 初期段階からテストカバレッジの計測をし 高カバレッジを実現する戦略を立てるべきだっ た
  33. ©︎tete marche CO., LTD. リニューアルチャンス 78 デザインのリニューアル をしたい デザインのリニューアルと Facebook

    SDKの置き換えを 同時に進めよう 対応後回しにしていたら PHPバージョンがEOL
  34. ©︎tete marche CO., LTD. 古いアプリケーションで開発を継続 89 このディレクトリ配下 で開発 • コードの移行が進まない

    (1年で全体の1/10) • その間サポートが切れたPHPバージョンで開発し続 けなければいけない • コードの移行は進まないが、機能開発は進んでいた ため、古いPHPバージョンのコードが増えていき、 移行が完了した後のバージョンアップ対応が大変
  35. ©︎tete marche CO., LTD. 教訓 95 ロードマップを作成し、期限を設けるべきだった • 移行にここまでの時間がかかることを見越せず、短期的に有効と思われる戦略を とってしまった

    • 初期段階で移行のロードマップを策定し、明確な期限を設けることで、移行を計 画的に進められたはず • どのくらいで移行が完了するかの目安を把握し、長期的視点でのトレードオフも 含めて判断できるようにすべきだった 古い環境のコードを増やさない戦略を徹底すべきだった • 古いアプリケーションでの開発を続けることによるデメリットや、後任者にかか るコストを軽視していて、短期的な成果を求めすぎた • 古い環境で開発を続ける後に続く人のコストを考え、新しいアプリケーションへ の移行が実現可能かをもっと真剣に検討する必要があった
  36. ©︎tete marche CO., LTD. 96 ドキュメント設計 • ドキュメント運用のルールを整備していないことで、多くの問題に繋がっていた • 対策としてADRを導入したが、プロダクト初期に意思決定された内容を、後から充実させることは困難

    • ドキュメント整備の不足は、設計者自身よりも、その後に引き継ぐ人たちに大きな負担を強いるため、最初からADRを導入 しておくべきだった テスト戦略 • フロントエンドのテストが手動テストに依存しすぎていてアイスクリームコーン型になっていた • アイスクリームコーン型自体は悪ではないが、現状維持に満足していると、長期的なコストが増大し、また後からテストを 充実させることが難しくなる • バックエンドは自動テスト化していたが、テストカバレッジの測定をしておらず、テストが充実していないことに気付けな かった • テストカバレッジだけではテストの品質が良いことを判断できないが、テストの品質が悪いことの判断はできるので、初期 段階からカバレッジを測定し高カバレッジを実現する戦略を立てるべきだった 移行戦略 • 短期的な成果を求めた結果、古い環境で開発を続ける決断をし、長期的に多くのコストがかかる戦略をとってしまった • 古い環境で開発を続けるデメリットを理解し、古い環境のコードを増やさないために、ストラングラーパターンに沿った移 行を進めればよかった まとめ