general-best-practices

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

さまざまな技術スタックやプロジェクトタイプに適用できる、ソフトウェア開発のベストプラクティスを包括的にまとめています。

コード品質

読みやすさと保守性

単一の責任を持つ、短く焦点の定まった関数を書きます。

変数、関数、クラスには、明確で説明的な名前を付けます。

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

関数やメソッドは適切な長さに保ちます（通常は30行未満）。

エラー処理

エラーを黙って無視せず、必ず明示的に処理します。

追跡可能性とコンテキストを確保するため、ラップしたエラーを使用します。

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

開発中は、問題が発生したら即座に、明確に失敗させます。

コードの構成

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

関心事を分離し、ビジネスロジックをインフラストラクチャコードから切り離します。

一貫性のあるファイル名とフォルダー名の規則を使用します。

API 設計では、予想外の挙動を避ける原則に従います。

アーキテクチャ

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

コードを次のような個別のレイヤーに構成します。

• プレゼンテーション／ハンドラー：外部からのリクエストとレスポンスを処理します
• アプリケーション／サービス：ビジネスオペレーションを調整します
• ドメイン：中核となるビジネスロジックとエンティティを担います
• インフラストラクチャ：外部システム、データベース、フレームワークを扱います

設計原則

継承よりもコンポジションを優先します。

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

テスト容易性と柔軟性を高めるため、依存性注入を使用します。

変更に備えて設計し、ビジネスロジックを切り離してフレームワークへの依存を最小限に抑えます。

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

テスト

単体テスト

高速で、分離され、繰り返し実行できるテストを書きます。

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

外部依存関係を適切にモックします。

ビジネス上重要なコードで、高いテストカバレッジを目指します。

統合テスト

コンポーネント間および外部システムとの連携をテストします。

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

テスト実行のたびにテストデータをクリーンアップします。

テストの構成

高速な単体テストと、時間のかかる統合テストを分けます。

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

CI/CD パイプラインにテストを組み込みます。

セキュリティ

入力の検証

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

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

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

認証と認可

トークンとセッションには、安全なデフォルト設定を使用します。

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

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

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

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

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

外部サービスへの呼び出しにはサーキットブレーカーを使用します。

パフォーマンス

最適化の原則

最適化の前にプロファイリングを行い、時期尚早な最適化を避けます。

定期的に測定とベンチマークを行います。

ホットパスと、頻繁に実行されるコードに注力します。

リソース管理

重要な処理経路でのメモリー割り当てを最小限に抑えます。

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

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

キャッシュ

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

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

キャッシュの一貫性と鮮度に関する要件を考慮します。

可観測性

ロギング

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

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

適切なログレベル（DEBUG、INFO、WARN、ERROR）で記録します。

機密情報をログに記録しないようにします。

メトリクス

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

異常やしきい値超過に対するアラートを設定します。

ダッシュボードを使用して、システムの健全性を可視化します。

トレーシング

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

サービス境界を越えてトレースコンテキストを伝播させます。

デバッグに役立つ重要な属性をスパンに記録します。

ドキュメント

コードのドキュメント

公開 API を明確に説明してください。

「何をするか」だけでなく、「なぜそうするのか」も説明してください。

説明対象のコードの近くにドキュメントを配置してください。

コードを変更したら、ドキュメントも更新してください。

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

セットアップ手順を含む、わかりやすい README を維持してください。

アーキテクチャ上の決定事項（ADR）を文書化してください。

チームメンバー向けのコントリビューションガイドラインを用意してください。

バージョン管理

コミットの方針

明確で簡潔なコミットメッセージを書いてください。

単一の論理的な変更を表す、アトミックなコミットを作成してください。

コミットは小さく、焦点を絞ってください。

ブランチ戦略

新しい開発にはフィーチャーブランチを使用してください。

main ブランチは安定した、デプロイ可能な状態に保ってください。

main にマージする前にコードをレビューしてください。

ツールと自動化

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

すべてのコミットでテストを自動実行してください。

コードのフォーマットとリンティングを徹底してください。

パイプラインにセキュリティスキャンを含めてください。

開発環境

チーム全体で一貫した開発環境を使用してください。

セットアップ手順と前提条件を文書化してください。

一般的な開発タスクを自動化してください。