software-architecture

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

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

コードスタイルのルール

一般原則

• 早期リターンパターン: 読みやすさのため、ネストした条件分岐よりも、可能な限り常に早期リターンを使用してください
• 再利用可能な関数とモジュールを作成して、コードの重複を避けてください
• 長い（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
• 覚えておいてください: 独自のコードの一行一行が、保守、テスト、ドキュメント作成を必要とする負債になります

コード品質

• 型付きの catch ブロックを用いた適切なエラーハンドリングを行ってください
• 複雑なロジックは、より小さく再利用可能な関数に分解してください
• 深いネストを避けてください（最大 3 階層）
• 可能な場合は、関数を焦点を絞った状態に保ち、50 行未満にしてください
• 可能な場合は、ファイルを焦点を絞った状態に保ち、200 行未満にしてください