ドキュメントの書き方

コメント、コミットメッセージ、報告書など、エンジニアが書くドキュメントの書き方を学びます。

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

1. 読み手を意識する

• 誰が読むのか（上司、同僚、将来の自分）
• 何を知りたいのか
• どの程度の前提知識があるか

2. 結論を先に書く

• 最初に結論や要点を書く
• 詳細は後から説明
• 忙しい人でも要点が分かるように

3. 構造化する

• 見出しをつける
• 箇条書きを活用
• 長文を避ける

コメントの書き方

良いコメントの原則

「なぜ」を書く

// 良い例：なぜそうしているかを説明
// 税率は法改正で変更される可能性があるため、定数として定義
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を再起動してください

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

• 自分で手順通りにやってみる
• 別の人に試してもらう
• 不明点があれば修正する

まとめ

コメント

• 「なぜ」を書く
• コードを日本語に訳さない
• 古くなったら更新する

コミットメッセージ

• 種類と要約を明確に
• 具体的に何をしたか分かるように

報告書

• 結論を先に書く
• 構造化して読みやすく

手順書

• 1ステップ1操作
• 自分で試してから共有