ドキュメンテーション

ドキュメントの種類と目的

ドキュメントは一種類ではありません。読み手が誰で、いつ必要とするかによって、 書くべき内容と形式が変わります。目的に合わないドキュメントは、書いても読まれず、 すぐに実態と乖離して「嘘の情報源」になってしまいます。

良いREADMEの構成

READMEは「このプロジェクトに初めて触れた人が迷わず動かせるようになる」ことがゴールです。

# ① README.md の構成例
# プロジェクト名

1行でこのプロジェクトが何をするものかを説明する。

## セットアップ
```bash
npm install
npm run dev
```

## 使い方
主要なコマンドや、最初に試すべき操作を書く。

## ディレクトリ構成
迷わないための最小限の地図（詳細はコードを読ませる）。

## 開発への参加方法
テストの実行方法、コーディング規約へのリンクなど。

すべての詳細を書き切ろうとせず、「まず動かす」までの最短距離を示すことに集中します。 詳細な仕様は別ドキュメントやコードそのものに任せます。

コードコメントの書き方

「何をしているか」はコード自体と良い命名で語らせ、コメントはコードだけでは伝わらない背景・理由を補うために使います。

// ユーザーを取得する
const user = getUser(id);

// 決済APIの仕様上、キャンセル済み
// ユーザーもここで取得できてしまうため
// 呼び出し側で状態チェックが必須
const user = getUser(id);

ドキュメントを腐らせないために

• • コードの変更とドキュメントの更新を同じPRに含める
• • 実装から自動生成できる部分（APIスキーマ等）は自動生成に任せる
• • 古くなったドキュメントは削除する勇気を持つ（誤情報より無い方がまし）
• • 「なぜ」を記録するADR等は変更せず追記していく（歴史として残す）