system-design

ソフトウェアアーキテクチャ開発スキル

このスキルは、品質を重視したソフトウェア開発とアーキテクチャに関するガイダンスを提供します。クリーンアーキテクチャとドメイン駆動設計の原則に基づいています。

コードスタイルのルール

一般原則

• 早期リターンパターン：可読性を高めるため、ネストした条件分岐よりも、可能な限り早期リターンを使用してください。
• 再利用可能な関数やモジュールを作成し、コードの重複を避けてください。
• 長い（コードが80行を超える）コンポーネントや関数は、複数の小さなコンポーネントや関数に分割してください。他の場所で使用できない場合は、同じファイル内に置いてください。ただし、ファイルのコードが200行を超える場合は、複数のファイルに分割してください。
• 可能な場合は、関数宣言ではなくアロー関数を使用してください。

ベストプラクティス

ライブラリ優先のアプローチ

• カスタムコードを書く前に、必ず既存の解決策を探してください。
  • 問題を解決する既存のライブラリがないかnpmで確認してください。
  • 既存のサービスやSaaSソリューションを評価してください。
  • 一般的な機能にはサードパーティAPIの利用を検討してください。
• 独自のユーティリティやヘルパーを書くのではなく、ライブラリを使用してください。たとえば、独自のリトライロジックを書く代わりにcockatielを使用してください。
• カスタムコードが正当化される場合：
  • ドメイン固有の、独自のビジネスロジック
  • 特別な要件がある、パフォーマンスが重要な処理経路
  • 外部依存関係が過剰になる場合
  • 完全な制御が必要な、セキュリティ上重要なコード
  • 十分に評価した後も、既存の解決策が要件を満たさない場合

アーキテクチャと設計

• クリーンアーキテクチャとDDDの原則：
  • ドメイン駆動設計とユビキタス言語に従ってください。
  • ドメインエンティティをインフラストラクチャ上の関心事から分離してください。
  • ビジネスロジックをフレームワークから独立させてください。
  • ユースケースを明確に定義し、分離してください。
• 命名規則：
  • 汎用的な名前（utils、helpers、common、shared）は避けてください。
  • ドメイン固有の名前（OrderCalculator、UserAuthenticator、InvoiceGenerator）を使用してください。
  • 境界づけられたコンテキストの命名パターンに従ってください。
  • 各モジュールの目的は、単一かつ明確にしてください。
• 関心事の分離：
  • ビジネスロジックとUIコンポーネントを混在させないでください。
  • データベースクエリをコントローラーに含めないでください。
  • コンテキスト間の境界を明確に保ってください。
  • 責務を適切に分離してください。

避けるべきアンチパターン

• NIH（Not Invented Here）症候群：
  • Auth0やSupabaseがある場合に、独自の認証機能を構築しないでください。
  • ReduxやZustandを使わずに、独自の状態管理を実装しないでください。
  • 定評のあるライブラリを使わずに、独自のフォームバリデーションを作成しないでください。
• 不適切なアーキテクチャの選択：
  • ビジネスロジックとUIコンポーネントの混在
  • コントローラー内での直接的なデータベースクエリ
  • 関心事の分離が不明確
• 汎用的な命名のアンチパターン：
  • 関連性のない関数が50個含まれるutils.js
  • 何でも詰め込む場所としてのhelpers/misc.js
  • 目的が不明確なcommon/shared.js
• 覚えておいてください。カスタムコードは1行ごとに、保守、テスト、ドキュメント整備が必要な負担となります。

コード品質

• 型付きcatchブロックで適切にエラーを処理する
• 複雑なロジックを、より小さく再利用可能な関数に分割する
• 深いネスト（最大3階層）を避ける
• 可能な限り、関数の役割を絞り、50行未満に保つ
• 可能な限り、ファイルの役割を絞り、コードを200行未満に保つ