ドキュメントの書き方

ドキュメントを書く基本原則

1. 読み手を意識する

ドキュメントを書く際は、誰が読むのかを常に考えることが重要です。

• 読み手は誰か（上司、同僚、将来の自分など）
• 何を知りたいのか（目的を理解する）
• どの程度の前提知識があるか（説明レベルを調整）

例えば、新入社員向けのドキュメントと経験豊富な開発者向けのドキュメントでは、説明の詳しさが異なります。読み手の視点で「分かりやすいか」を常に問い直しましょう。

2. 結論を先に書く

忙しい人でも要点が分かるように、最初に結論や要点を書くことが重要です。

• 最初の1段落で結論を示す
• 詳細な説明は後から追加
• 読者が必要な情報を素早く見つけられる

つまり「結論→理由→詳細」の順序で書くことで、読者が自分に必要な情報を選別できるようにします。

3. 構造化する

情報を見出し、箇条書き、表などで整理することで、読みやすさが大きく向上します。

• 見出しで内容を分ける
• 箇条書きで項目を列挙
• 長文を避ける（1段落は3～5行程度が目安）
• 表で比較・分類

読者は全文を丁寧に読むのではなく、見出しで必要な箇所をスキャンして読みます。構造化することで、読者にとって情報が見つけやすくなります。

コメントの書き方

良いコメントの原則：「なぜ」を書く

コードを見れば「何をしているか」は分かります。大切なのは「なぜそうしているか」を説明することです。

// 良い例：なぜそうしているかを説明
// 税率は法改正で変更される可能性があるため、定数として定義
final double TAX_RATE = 0.10;

// 悪い例：何をしているかを説明（コードを見れば分かる）
// 税率を0.10に設定
final double TAX_RATE = 0.10;

良いコメントの例

// 外部APIの仕様により、日付はYYYYMMDD形式で送信する必要がある
String dateStr = date.format(DateTimeFormatter.ofPattern("yyyyMMdd"));

// パフォーマンス改善のため、100件ずつバッチ処理する
// 一度に全件処理すると、メモリ不足になる可能性がある
for (int i = 0; i < items.size(); i += 100) {
    processBatch(items.subList(i, Math.min(i + 100, items.size())));
}

悪いコメントの例

避けるべきコメントのパターン：

// 悪い例1：コードを日本語に訳しただけ
// ループを10回繰り返す
for (int i = 0; i < 10; i++) {

// 悪い例2：古くなって嘘になっている
// ユーザー名の最大長は20文字
// （実際は50文字に変更済み）
if (name.length() > 50) {

// 悪い例3：当たり前のことを書いている
// コンストラクタ
public User() {

ドキュメントコメント

メソッドやクラスには、ドキュメントコメントを書きます。

/**
 * 税込金額を計算する。
 *
 * @param amount 税抜金額
 * @return 税込金額（小数点以下切り捨て）
 * @throws IllegalArgumentException amountが負の値の場合
 */
public int calculateTaxIncluded(int amount) {
    if (amount < 0) {
        throw new IllegalArgumentException("金額は0以上である必要があります");
    }
    return (int) (amount * (1 + TAX_RATE));
}

コミットメッセージの書き方

基本形式

[種類] 変更内容の要約

詳細な説明（必要に応じて）

種類の例

良い例・悪い例

具体的でないメッセージは、後から歴史を辿るときに役に立ちません。

# 悪い例（何をしたか分からない）
修正
更新
対応
fix

# 良い例（具体的に分かる）
[fix] ログイン時のバリデーションエラーを修正
[add] ユーザー検索機能を追加
[update] メール送信処理のタイムアウト時間を30秒に変更
[refactor] UserServiceのメソッドを整理

詳細を書く場合

[fix] ログイン時のバリデーションエラーを修正

- メールアドレスの形式チェックが正しく動作していなかった
- 正規表現のパターンを修正
- 関連するテストケースを追加

Issue: #123

報告書の書き方

調査報告書の構成

技術的な調査結果をまとめるときの構成例：

# 〇〇の調査報告

## 結論
（最初に結論を書く）

## 調査内容
- 調査した項目1
- 調査した項目2

## 詳細
（具体的な調査結果）

## 対応案
1. 案A：〇〇
2. 案B：△△

## 備考
（補足事項）

進捗報告の構成

定期的な進捗状況を報告するときの構成：

# 進捗報告（YYYY/MM/DD）

## 完了したこと
- タスクA
- タスクB

## 進行中のこと
- タスクC（進捗50%）

## 問題・課題
- 〇〇でエラーが発生、原因調査中

## 次にやること
- タスクD
- タスクE

障害報告書の構成

本番環境の障害が発生したときの報告フォーマット：

# 障害報告書

## 概要
- 発生日時：YYYY/MM/DD HH:MM
- 影響範囲：〇〇機能
- 対応状況：復旧済み

## 事象
（何が起きたか）

## 原因
（なぜ起きたか）

## 対応内容
（何をしたか）

## 再発防止策
（今後どうするか）

手順書の書き方

良い手順書の特徴

• 番号付きで順序が明確：ステップの順序が大切
• 1ステップ1操作：細かく分割する
• 前提条件が明記：どのような状態から始めるか
• スクリーンショットや例がある：視覚的な補助

手順書の例

# 開発環境構築手順

## 前提条件
- Windows 10 以上
- 管理者権限があること

## 手順

### 1. Node.js のインストール
1. https://nodejs.org/ にアクセス
2. LTS版をダウンロード
3. ダウンロードしたファイルを実行
4. インストーラーの指示に従ってインストール

### 2. 動作確認
1. コマンドプロンプトを開く
2. `node -v` を実行
3. バージョン番号が表示されればOK

## トラブルシューティング
- 「コマンドが見つかりません」と出る場合
  → PCを再起動してください

手順書を書いた後にやること

• 自分で手順通りにやってみる：ステップに漏れや誤りがないか
• 別の人に試してもらう：別の人の視点で不明点を見つける
• 不明点があれば修正する：フィードバックを反映

まとめ

心がけ：

• 「読み手の視点」でドキュメントを評価する
• 迷ったときは読み手にとって「分かりやすいか」を問い直す
• 書いた後は、自分以外の人に読んでもらってフィードバックをもらう