# コーディング規約・命名規則

## 規約の目的

- コードの可読性・保守性の向上
- チーム内での一貫したコーディングスタイルの維持
- バグの混入リスクの低減
- レビュー効率の向上

---

## 言語別コーディング規約

本プロジェクトでは、以下の公式または広く採用されているコーディング規約に準拠する。

### Java
- [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html)
- または [Oracle Code Conventions for Java](https://www.oracle.com/java/technologies/javase/codeconventions-contents.html)

### TypeScript/JavaScript
- [Google TypeScript Style Guide](https://google.github.io/styleguide/tsguide.html)
- [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript)

### Python
- [PEP 8 -- Style Guide for Python Code](https://peps.python.org/pep-0008/)

### C#
- [Microsoft C# Coding Conventions](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/coding-conventions)

### その他の言語
- [使用言語]: [採用する規約のURL]

---

## 命名規則

### 基本原則
- 意味のある名前を使用する（略語は避ける）
- 英語を使用する（ローマ字表記は避ける）
- 予約語との衝突を避ける
- プロジェクト全体で一貫性を保つ

### 言語共通の命名規則

| 対象 | 命名規則 | 例 |
|------|---------|-----|
| クラス名 | PascalCase | `UserService`, `OrderRepository` |
| インターフェース名 | PascalCase (Iプレフィックス) | `IUserRepository`, `IPaymentGateway` |
| メソッド名 | camelCase | `getUserById`, `calculateTotal` |
| 変数名 | camelCase | `userName`, `totalAmount` |
| 定数 | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT`, `DEFAULT_TIMEOUT` |
| プライベート変数 | _camelCase | `_userId`, `_connectionPool` |
| Boolean変数 | is/has/canで始める | `isActive`, `hasPermission`, `canEdit` |

### 言語別の命名規則補足

#### Java
```java
// パッケージ名: 小文字のみ、ドット区切り
package com.example.project.service;

// クラス名: PascalCase
public class UserService {
    // 定数: UPPER_SNAKE_CASE
    private static final int MAX_RETRY_COUNT = 3;
    
    // プライベート変数: camelCase
    private String userName;
    
    // メソッド名: camelCase
    public User getUserById(String userId) {
        // ローカル変数: camelCase
        String fullName = user.getFirstName() + " " + user.getLastName();
        return user;
    }
}
```

#### TypeScript/JavaScript
```typescript
// ファイル名: kebab-case
// user-service.ts

// クラス名: PascalCase
export class UserService {
    // プライベート変数: _camelCase
    private _userRepository: IUserRepository;
    
    // メソッド名: camelCase
    public async getUserById(userId: string): Promise<User> {
        const user = await this._userRepository.findById(userId);
        return user;
    }
}

// 定数: UPPER_SNAKE_CASE
export const MAX_RETRY_COUNT = 3;

// 型名: PascalCase
export type UserRole = 'admin' | 'user' | 'guest';
```

#### Python
```python
# ファイル名: snake_case
# user_service.py

# クラス名: PascalCase
class UserService:
    # クラス変数（定数）: UPPER_SNAKE_CASE
    MAX_RETRY_COUNT = 3
    
    def __init__(self):
        # プライベート変数: _snake_case
        self._user_repository = UserRepository()
    
    # メソッド名: snake_case
    def get_user_by_id(self, user_id: str) -> User:
        user = self._user_repository.find_by_id(user_id)
        return user

# 関数名: snake_case
def calculate_total_amount(items: list) -> float:
    return sum(item.price for item in items)
```

### AWSリソースの命名規則

```mermaid
graph TD
    A[AWSリソース命名規則] --> B[基本フォーマット]
    A --> C[環境識別子]
    A --> D[リソース種別]
    
    B --> B1["<プロジェクト>-<環境>-<リソース種別>-<用途>"]
    C --> C1[dev: 開発環境]
    C --> C2[stg: ステージング環境]
    C --> C3[prd: 本番環境]
    
    D --> D1[EC2: ec2]
    D --> D2[S3: s3]
    D --> D3[RDS: rds]
    D --> D4[Lambda: lambda]
```

#### 命名規則の詳細

**基本フォーマット:**
```
<プロジェクト名>-<環境>-<リソース種別>-<用途>-<連番>
```

**例:**
| リソース | 命名例 | 説明 |
|---------|--------|------|
| S3バケット | `myapp-prd-s3-assets` | 本番環境の静的アセット用S3 |
| EC2インスタンス | `myapp-dev-ec2-web-01` | 開発環境のWebサーバー1号機 |
| RDS | `myapp-stg-rds-main` | ステージング環境のメインDB |
| Lambda | `myapp-prd-lambda-order-processor` | 本番環境の注文処理Lambda |
| IAMロール | `myapp-prd-role-lambda-execution` | Lambda実行用IAMロール |
| Security Group | `myapp-dev-sg-web` | 開発環境Web層のSG |
| VPC | `myapp-prd-vpc` | 本番環境のVPC |
| Subnet | `myapp-prd-subnet-public-1a` | 本番環境パブリックサブネット(AZ-1a) |

#### タグ付け規則

すべてのAWSリソースには以下のタグを必須とする:

| タグキー | 説明 | 例 |
|---------|------|-----|
| Project | プロジェクト名 | myapp |
| Environment | 環境 | production, staging, development |
| Owner | 管理者 | team-backend |
| CostCenter | コストセンター | engineering |
| ManagedBy | 管理方法 | terraform, cloudformation, manual |

---

## ファイル・ディレクトリ構成

### ディレクトリ構造の基本方針

```
project-root/
├── src/                    # ソースコード
│   ├── domain/            # ドメイン層（ビジネスロジック）
│   ├── application/       # アプリケーション層
│   ├── infrastructure/    # インフラ層（DB、外部API等）
│   └── presentation/      # プレゼンテーション層（UI、API）
├── tests/                 # テストコード
│   ├── unit/             # 単体テスト
│   ├── integration/      # 結合テスト
│   └── e2e/              # E2Eテスト
├── docs/                  # ドキュメント
├── scripts/               # ビルド・デプロイスクリプト
└── config/                # 設定ファイル
```

### ファイル命名規則

| ファイル種別 | 命名規則 | 例 |
|------------|---------|-----|
| ソースファイル | クラス名と一致 | `UserService.ts` |
| テストファイル | `*.test.*` または `*.spec.*` | `user-service.test.ts` |
| 設定ファイル | kebab-case | `database-config.yaml` |
| スクリプトファイル | kebab-case | `deploy-production.sh` |

---

## コメント規約

### 基本方針
- コードで表現できることはコードで表現する
- 「何をするか」ではなく「なぜそうするか」を書く
- 不要なコメントアウトコードは削除する
- TODOコメントには担当者と期限を記載する

### ドキュメントコメント

公開API、複雑なビジネスロジックには必ずドキュメントコメントを記載する。

#### Java (Javadoc)
```java
/**
 * ユーザー情報を取得する
 *
 * @param userId ユーザーID
 * @return ユーザー情報。存在しない場合はnull
 * @throws DatabaseException DB接続エラー時
 */
public User getUserById(String userId) throws DatabaseException {
    // 実装
}
```

#### TypeScript (JSDoc)
```typescript
/**
 * ユーザー情報を取得する
 * @param userId - ユーザーID
 * @returns ユーザー情報のPromise
 * @throws {DatabaseError} DB接続エラー時
 */
async getUserById(userId: string): Promise<User> {
    // 実装
}
```

#### Python (Docstring)
```python
def get_user_by_id(user_id: str) -> User:
    """
    ユーザー情報を取得する
    
    Args:
        user_id: ユーザーID
        
    Returns:
        User: ユーザー情報
        
    Raises:
        DatabaseError: DB接続エラー時
    """
    # 実装
```

### インラインコメント

```typescript
// 良い例: 「なぜ」を説明
// タイムアウトを長めに設定（外部APIのレスポンスが遅いため）
const TIMEOUT = 30000;

// 悪い例: コードを繰り返しているだけ
// タイムアウトを30000に設定
const TIMEOUT = 30000;
```

### TODOコメント

```typescript
// TODO(yamada 2025-12-15): エラーハンドリングを改善
// FIXME: メモリリークの可能性あり
// HACK: 一時的な対応。APIの仕様確定後に修正予定
```

---

## 静的解析ツールの活用

### 導入ツール

| 言語 | ツール | 用途 | 設定ファイル |
|------|--------|------|-------------|
| Java | Checkstyle | スタイルチェック | `checkstyle.xml` |
| Java | SpotBugs | バグ検出 | `spotbugs.xml` |
| TypeScript | ESLint | リント | `.eslintrc.json` |
| TypeScript | Prettier | フォーマット | `.prettierrc` |
| Python | pylint | リント | `.pylintrc` |
| Python | black | フォーマット | `pyproject.toml` |
| C# | StyleCop | スタイルチェック | `.editorconfig` |

### CI/CDでの実行

すべての静的解析ツールはCI/CDパイプラインで自動実行し、違反があればビルドを失敗させる。

```yaml
# GitHub Actions の例
- name: Run ESLint
  run: npm run lint
  
- name: Run Prettier Check
  run: npm run format:check
```

---

## レビュー観点

### チェックリスト

- [ ] 命名規則に準拠しているか
- [ ] 適切なコメントが記載されているか
- [ ] 重複コードはないか
- [ ] エラーハンドリングは適切か
- [ ] セキュリティ上の問題はないか
- [ ] パフォーマンス上の問題はないか
- [ ] テストコードは十分か
- [ ] ドキュメントは更新されているか

### レビュー時の注意事項

- 建設的なフィードバックを心がける
- 重要度に応じて「Must」「Should」「Nice to have」を明示する
- コードスタイルは静的解析ツールに任せ、ロジックに集中する

---

## 例外規約

以下の場合は、規約の適用を緩和または除外することができる:

- 外部ライブラリのインターフェースに合わせる必要がある場合
- レガシーコードとの整合性を保つ必要がある場合
- パフォーマンス上の理由がある場合

例外を適用する場合は、コメントで理由を明記すること。

```typescript
// 外部ライブラリの仕様に合わせてスネークケースを使用
const api_key = process.env.EXTERNAL_API_KEY;
```

---