documentation

ドキュメント

文体はwriting-voiceに従ってください。アーキテクチャの解説、フォルダーのメンタルモデル、新規参加者向けの説明では、所有者、境界、またはフローから説明を始めてください。必要に応じて、コードに基づいてモデルを説明し、誤解されやすい点にも触れてください。

ドキュメントでは「何をするか」ではなく、なぜそうするかを説明します。何をするかは、コードを読めばわかります。読者が知りたいのは、その判断の理由です。

フォルダーのREADME

主な役割は、このフォルダーがなぜ存在するのかと、そのメンタルモデルを説明することです。

有用なモデルから説明を始めてください。このフォルダーが何を所有し、なぜ存在するのか、今後の編集でどの境界を守るべきかを説明します。

含めてもよいもの

• 複雑な関係を示すASCII図
• 主要なエクスポートやエントリーポイントの概要
• ファイル名だけでは伝わらない背景を補う簡潔なファイルの説明
• 他のフォルダーとの関係

避けるもの

• lsの結果をそのまま繰り返すだけの網羅的なファイル一覧
• ファイル名をそのまま説明する記述（「auth.ts - 認証」など）
• コードで表現するほうが適切な実装の詳細

良い例

# Converters

Transform field schemas into format-specific representations.

```
┌─────────────┐     ┌──────────────┐
│ Field Schema│────▶│  to-arktype  │────▶ Runtime validation
└─────────────┘     ├──────────────┤
                    │  to-drizzle  │────▶ SQLite columns
                    └──────────────┘
```

Field schemas are pure JSON Schema objects with `x-component` hints. Each converter takes the same input and produces output for a specific consumer.

悪い例

# Converters

- `to-arktype.ts` - Converts to ArkType
- `to-drizzle.ts` - Converts to Drizzle
- `index.ts` - Exports

悪い例は、新しいコンバーターを追加するパターンやタイミングを説明せず、ファイルを列挙しているだけです。

JSDocコメント

JSDocでは、何をするかだけでなく、いつ、なぜ使うのかを説明します。

良い例

/**
 * Get all table helpers as an array.
 *
 * Useful for providers and indexes that need to iterate over all tables.
 * Returns only the table helpers, excluding utility methods like `clearAll`.
 *
 * @example
 * ```typescript
 * for (const table of tables.defined()) {
 *   console.log(table.name, table.count());
 * }
 * ```
 */
defined() { ... }

悪い例

/** Returns all table helpers as an array. */
defined() { ... }

ルール

• 現実的な使い方を示す@exampleブロックを含める
• 何をするかだけでなく、いつ使うかを説明する
• わかりにくい動作やエッジケースを記録する
• 公開APIには詳細なドキュメントを付け、内部ヘルパーは簡潔な説明でかまいません

コードコメント

コメントでは「何をするか」ではなく、なぜそうするかを説明します。

良い例

// Y.Doc clientIDs are random 32-bit integers, so we can't rely on ordering.
// Use timestamps from the entries themselves for deterministic sorting.
const sorted = entries.sort((a, b) => a.timestamp - b.timestamp);

悪い例

// Sort the entries
const sorted = entries.sort((a, b) => a.timestamp - b.timestamp);

ルール

• コードが明確なら、コメントを付けない
• 理由が明らかでない場合に「なぜ」を説明する
• 回避策には、課題やドキュメントへのリンクを付ける
• コメントアウトされたコードは削除する。履歴を確認するにはgitを使います