コンテンツにスキップ

01.共通コーディング原則

このドキュメントは、プログラミング言語に依存しない、全てのコードに共通する普遍的な原則や思想を定義します。 ここに書かれている原則は、全てのコーディング規約の基礎となります。

思想の核心

コードは、コンピューターのためだけでなく、未来の自分自身とチームメイトのために書く。

1. 可読性 (Readability)

コードは書く時間より読まれる時間の方が圧倒的に長い。未来の自分や他のメンバーが、容易に内容を理解できるコードを書くことを常に最優先とします。

  • 明確な命名:
    • 変数名、関数名、クラス名は、その役割や意図が明確に伝わるように、具体的かつ分かりやすい名前を付けます。
    • 曖昧な省略（例: i, j, tmp, data）や、意味のない名前は、ループカウンターなどの限定的な場合を除き避けてください。
  • 一貫性のあるスタイル:
    • プロジェクト内で、インデント、スペーシング、命名規則などのスタイルを一貫させます。
    • 具体的なスタイルは、各言語の規約に従ってください。自動フォーマッターの導入を強く推奨します。

2. シンプルさ (Simplicity)

  • KISSの原則 (Keep It Simple, Stupid):
    • 複雑な問題を、できるだけシンプルで小さな問題に分割して解決します。不必要に複雑なロジックや、過剰な設計は避けてください。
  • YAGNIの原則 (You Ain't Gonna Need It):
    • 「将来必要になるかもしれない」という予測だけで、前もって機能を実装しないでください。本当に必要になった時に、必要なものだけをシンプルに実装します。

3. 保守性 (Maintainability)

  • DRYの原則 (Don't Repeat Yourself):
    • 同じロジックや情報（マジックナンバーなど）を、複数の場所に重複して記述しないでください。共通化できるものは、関数や定数として抽出し、一元管理します。
  • 単一責任の原則 (Single Responsibility Principle):
    • 一つの関数やクラスは、一つの明確な責務だけを持つように設計します。複数の責務を持つ巨大な関数やクラスは、適切に分割してください。
  • コメントの哲学:
    • コードが「何をしているか(What)」を説明するコメントは、コード自体が明確であれば不要です。
    • コメントは、そのコードの「なぜそうなっているのか(Why)」という、コードだけでは表現しきれない設計意図、背景、トレードオフ、あるいは将来の改善点を説明するために使用します。

4. 堅牢性 (Robustness)

  • エラーハンドリング:
    • エラーは握りつぶさず、適切に処理または上位に伝達します。関数の呼び出し元が、成功したか失敗したかを明確に判断できるように設計してください。
  • 入力値の検証:
    • 外部からの入力（ユーザー入力、APIリクエスト、ファイルなど）は、常に「信頼できない」ものとして扱ってください。受け取った時点で、必ず厳格な検証（バリデーション）を行います。

5. 要求仕様とのトレーサビリティ

  • 機能の実装や修正、テストコードなど、特定の要求仕様に対応するコードには、関連する要求IDをコメントとして明記することを推奨します。
  • これにより、コードの変更がどの要求に基づくものなのかを、後から追跡することが可能になります。 
    // REQ-AUTH-1.2: アカウントロックのロジック
if (loginAttempts > MAX_ATTEMPTS) {
    // ...
}