コードドキュメンテーション

README の構成

標準的な README テンプレート

# Project Name

このプロジェクトが何をするかについての簡潔な説明。

## クイックスタート

\`\`\`bash
npm install
npm run dev
\`\`\`

## インストール

詳細なインストール手順...

## 使用方法

\`\`\`typescript
import { something } from 'project';

// 使用例
const result = something.doThing();
\`\`\`

## API リファレンス

### `functionName(param: Type): ReturnType`

関数が何を行うかについての説明。

**パラメータ:**
- `param` - パラメータの説明

**戻り値:** 戻り値の説明

**例:**
\`\`\`typescript
const result = functionName('value');
\`\`\`

## 設定

| オプション | 型 | デフォルト | 説明 |
|--------|------|---------|-------------|
| `option1` | `string` | `'default'` | 機能説明 |

## 貢献

貢献方法...

## ライセンス

MIT

API ドキュメンテーション

JSDoc/TSDoc スタイル

/**
 * 新しいユーザーアカウントを作成します。
 *
 * @param userData - アカウント作成用のユーザーデータ
 * @param options - オプション設定
 * @returns 作成されたユーザーオブジェクト
 * @throws {ValidationError} メールアドレスが無効な場合
 * @example
 * ```ts
 * const user = await createUser({
 *   email: 'user@example.com',
 *   name: 'John'
 * });
 * ```
 */
async function createUser(
  userData: UserInput,
  options?: CreateOptions
): Promise<User> {
  // 実装
}

/**
 * API クライアントの設定オプション。
 */
interface ClientConfig {
  /** API ベース URL */
  baseUrl: string;
  /** リクエストタイムアウト（ミリ秒） @default 5000 */
  timeout?: number;
  /** リクエストに含める カスタムヘッダー */
  headers?: Record<string, string>;
}

OpenAPI/Swagger

openapi: 3.0.0
info:
  title: My API
  version: 1.0.0

paths:
  /users:
    post:
      summary: ユーザーを作成
      description: 新しいユーザーアカウントを作成します
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserInput'
      responses:
        '201':
          description: ユーザーが正常に作成されました
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: 無効な入力

components:
  schemas:
    UserInput:
      type: object
      required:
        - email
        - name
      properties:
        email:
          type: string
          format: email
        name:
          type: string
    User:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
        name:
          type: string
        createdAt:
          type: string
          format: date-time

インラインコメント

コメントを書くべき場合

// 良い例: 何かではなく、なぜかを説明する

// リストは常にソート済みで、
// 数百万の項目が含まれる可能性があるため二分探索を使用 - O(log n) vs O(n)
const index = binarySearch(items, target);

// 良い例: 複雑なビジネスロジックを説明する
// ユーザーが 2 年以上のメンバーであり、
// かつ 10 回以上の購入を行った場合は 20% の割引を適用
// (2024年第4四半期のマーケティングチーム決定による)
if (user.memberYears >= 2 && user.purchaseCount >= 10) {
  applyDiscount(0.2);
}

// 良い例: ワークアラウンドを文書化する
// HACK: Safari はこの API をサポートしていないため、ポーリングにフォールバック
// TODO: Safari がサポートを追加したら削除 (tracking: webkit.org/b/12345)
if (!window.IntersectionObserver) {
  startPolling();
}

コメントを書くべきでない場合

// 悪い例: 明らかなことを述べている
// カウンターを1増やす
counter++;

// 悪い例: 明確なコードを説明している
// ユーザーが管理者かどうかを確認
if (user.role === 'admin') { ... }

// 悪い例: 古いコメント（コメントがないより悪い）
// ユーザーのフルネームを返す  <-- 実際にはメールを返す!
function getUserIdentifier(user) {
  return user.email;
}

アーキテクチャドキュメンテーション

ADR (Architecture Decision Record)

# ADR-001: プライマリーデータベースに PostgreSQL を使用

## ステータス
承認済み

## 背景
ユーザーデータとトランザクションを保存するためのデータベースが必要。
検討されたオプション: PostgreSQL、MySQL、MongoDB、DynamoDB。

## 決定
PostgreSQL と Supabase ホスティングを使用する。

## 根拠
- 財務データに強い ACID コンプライアンスが必要
- チームに PostgreSQL の経験がある
- Supabase は認証とリアルタイム機能を提供する
- pgvector 拡張機能で将来の AI 機能に対応

## 結果
- スキーママイグレーションを管理する必要がある
- スケール時にリードレプリカが必要な可能性がある
- チームが Supabase 固有の機能を学ぶ必要がある

コンポーネントドキュメンテーション

## 認証モジュール

### 概要
リフレッシュトークンローテーション付き JWT トークンを使用したユーザー認証を処理します。

### フロー
1. ユーザーが `/auth/login` に認証情報を送信
2. サーバーが検証し、アクセストークン + リフレッシュトークンを返す
3. アクセストークンが API リクエストに使用される (15分の有効期限)
4. リフレッシュトークンが新しいアクセストークンの取得に使用される (7日の有効期限)

### 依存関係
- `jsonwebtoken` - トークンの生成/検証
- `bcrypt` - パスワードハッシング
- `redis` - リフレッシュトークンストレージ

### 設定
- `JWT_SECRET` - トークン署名用のシークレット
- `ACCESS_TOKEN_EXPIRY` - アクセストークンの有効期限
- `REFRESH_TOKEN_EXPIRY` - リフレッシュトークンの有効期限

ドキュメンテーションの原則

1. 対象読者に向けて書く - 新規開発者と API コンシューマーでは異なる
2. コードの近くに保つ - ドキュメントを同じリポジトリ内、関連コードの近くに配置
3. コードと一緒に更新する - 古いドキュメントはないよりも悪い
4. 説明より例を優先する - 説明するだけでなく、見せる
5. 段階的な情報開示 - クイックスタートを最初に、詳細は後で