一般的なベストプラクティス

さまざまなテクノロジースタックとプロジェクトタイプに適用可能な、包括的なソフトウェア開発のベストプラクティス集です。

コード品質

可読性と保守性

短く、焦点の絞られた関数を書き、単一の責務を持たせます。

変数、関数、クラスに対して明確で説明的な名前を使用します。

深いネストを避け、早期リターンとガード句を優先します。

関数とメソッドは合理的な長さに保ちます（通常は30行以下）。

エラーハンドリング

エラーを常に明示的に処理し、静かに無視することはしません。

トレーサビリティとコンテキストのために、ラップされたエラーを使用します。

デバッグに役立つ意味のあるエラーメッセージを提供します。

開発中は迅速かつ明確に失敗します。

コード構成

コードを論理的なモジュールとパッケージに整理します。

関心の分離：ビジネスロジックをインフラストラクチャコードから分けて保ちます。

一貫したファイルとフォルダの命名規則を使用します。

APIデザインでは最小驚愕の原則に従います。

アーキテクチャ

クリーンアーキテクチャの原則

コードを個別のレイヤーに構成します：

• Presentation/Handlers: 外部のリクエストとレスポンスを処理
• Application/Services: ビジネスオペレーションをオーケストレーション
• Domain: コアビジネスロジックとエンティティ
• Infrastructure: 外部システム、データベース、フレームワーク

デザイン原則

継承より合成を優先します。

実装ではなく、インターフェースをプログラミングします。

テスト可能性と柔軟性のために、依存性注入を使用します。

変更に対応するよう設計：ビジネスロジックを隔離し、フレームワークへのロックインを最小化します。

適切な場合は、SOLID原則を適用します。

テスト

ユニットテスト

高速で、独立し、再現可能なテストを書きます。

複数のシナリオをテストするために、テーブル駆動テストを使用します。

外部依存関係をクリーンにモックします。

ビジネスクリティカルなコードの高いテストカバレッジを目指します。

統合テスト

コンポーネント間および外部システムとの相互作用をテストします。

個別のテスト設定とデータベースを使用します。

各テスト実行後、テストデータをクリーンアップします。

テスト構成

高速なユニットテストを遅いテストから分離します。

開発中は高速テストを頻繁に実行します。

CI/CDパイプラインにテストを含めます。

セキュリティ

入力検証

サービス境界で全ての入力を検証します。

ユーザー入力を決して信頼せず、すべてをサニタイズして検証します。

SQLインジェクションを防ぐために、パラメータ化クエリを使用します。

認証と認可

トークンとセッションにセキュアなデフォルトを使用します。

すべてのレイヤーで適切なアクセス制御を実装します。

シークレットは安全に保管し、バージョン管理にはコミットしません。

ネットワークセキュリティ

すべての通信にHTTPSを使用します。

悪用を防ぐため、レート制限を実装します。

外部サービスコールにはサーキットブレーカーを使用します。

パフォーマンス

最適化の原則

最適化する前にプロファイリングを実施し、過度な最適化を避けます。

定期的に測定とベンチマークを実施します。

ホットパスと頻繁に実行されるコードに焦点を当てます。

リソース管理

クリティカルパスでのメモリ割り当てを最小化します。

データベースおよびネットワーク接続にはコネクションプーリングを使用します。

適切なリソースのクリーンアップと解放を実装します。

キャッシング

コストのかかる計算と頻繁にアクセスされるデータをキャッシュします。

適切なキャッシュ無効化戦略を使用します。

キャッシュの一貫性と鮮度要件を検討します。

可観測性

ログ出力

構造化ログ（本番環境ではJSON形式）を使用します。

リクエストID、ユーザーID、タイムスタンプなど関連するコンテキストを含めます。

適切なレベルでログを出力します：DEBUG、INFO、WARN、ERROR。

機密情報をログに出力しません。

メトリクス

主要なメトリクスを追跡します：レイテンシー、スループット、エラー率。

異常値と閾値超過に対するアラートを設定します。

システムヘルスの可視化のためダッシュボードを使用します。

トレーシング

マイクロサービスに分散トレーシングを実装します。

サービス境界をまたいでトレースコンテキストを伝播させます。

デバッグのため、スパンに重要な属性を記録します。

ドキュメント

コードドキュメント

公開APIは明確な説明でドキュメント化します。

「何」だけでなく「なぜ」を説明します。

ドキュメントをそれが説明するコードの近くに保ちます。

コードが変更されたときはドキュメントも更新します。

プロジェクトドキュメント

セットアップ手順を明記したREADMEを維持します。

アーキテクチャ決定記録（ADR）をドキュメント化します。

チームメンバーのための貢献ガイドラインを提供します。

バージョン管理

コミット実践

明確で簡潔なコミットメッセージを書きます。

単一の論理的な変更を表すアトミックコミットを作成します。

コミットは小さく、焦点を絞ったものに保ちます。

ブランチ戦略

新規開発にはフィーチャーブランチを使用します。

メインブランチは安定していてデプロイ可能に保ちます。

メインへのマージの前にコードレビューを実施します。

ツールと自動化

継続的インテグレーション

すべてのコミット時にテストを自動実行します。

コードフォーマットとリンティングを強制します。

パイプラインにセキュリティスキャンを含めます。

開発環境

チーム全体で一貫した開発環境を使用します。

セットアップステップと前提条件をドキュメント化します。

一般的な開発タスクを自動化します。