💻 コーディング基礎講座【第四回】コメント・ドキュメントを書こう！良いコメント・悪いコメント・マジックナンバー

1. 👋 はじめに

前回はDRY・KISS・単一責任などのコード設計原則を学びました。

今回は コメントとドキュメント を解説します！
※ なおサンプルコードはすべてPythonを使用しています。

「良いコードはコメントなしで読める。でも良いコメントはコードを超えた価値を持つ。」

コメントは「何をしているか」ではなく、「なぜそうしているか」を伝えるためのものです。

この記事を読めば：

• ✅ 良いコメント・悪いコメントの違いがわかる
• ✅ 「何を」ではなく「なぜ」を書く習慣がつく
• ✅ docstringの書き方がわかる
• ✅ マジックナンバーを排除する方法がわかる

---

2. 💬 コメントの種類

コメントには大きく2種類あります。

種類	目的	例
📝 インラインコメント	コードの横・上に書く短い説明	# ユーザーIDを検索キーに使う
📖 docstring	関数・クラスの仕様を書く文書	"""ユーザーを取得する。"""

---

3. ❌ 悪いコメントの5パターン

パターン①：コードの内容をそのまま書く（意味がない）

# ❌ コードを日本語に翻訳しただけ（読めばわかる）
# iを1増やす
i += 1

# ユーザーリストをループする
for user in users:
    # ユーザー名を表示する
    print(user.name)

# ✅ コメントがなくてもコードが語っている
for user in users:
    print(user.name)

コードを読めばわかることをコメントに書いても意味がありません。
「コードの翻訳」はコメントの仕事ではありません。

---

パターン②：古くなったコメント（嘘をつくコメント）

# ❌ コードは変わったのにコメントが古いまま
# 管理者のみアクセス可能
def get_all_users() -> list[User]:
    # ← 実際には全ユーザーがアクセスできるように変更されたのに
    #   コメントが更新されていない！
    return db.query("SELECT * FROM users")

⚠️ 古いコメントはないコメントより有害です。
コードを修正したときは必ずコメントも一緒に確認・更新しましょう。
嘘をつくコメントはバグの原因になります。

「コードは嘘をつかないが、コメントは簡単に嘘をつく」
コメントは書いた瞬間から「腐り始める」もので、常にメンテナンスのコストが発生します。
むやみにコメントを増やすのではなく、まずコード自体をシンプルで読みやすく書くことを優先しましょう（KISS原則）。
コメントは「コードでは伝えきれない情報」にだけ使うのが鉄則です。

---

パターン③：コメントアウトされたコード

# ❌ 使わなくなったコードをコメントアウトして残している
def calculate_price(price: int, quantity: int) -> int:
    # total = price * quantity * 1.08  # 旧消費税率
    # if total > 10000:
    #     total = total * 0.9  # 旧割引ロジック
    total = price * quantity * 1.10
    return total

⚠️ コメントアウトされたコードは削除しましょう！
「後で使うかもしれないから」という理由で残しがちですが、
Gitで管理しているのでいつでも過去のコードに戻れます。
コメントアウトされたコードはコードベースを汚染し、
「なぜ残っているのか」という混乱を生みます。

---

パターン④：自明なことを書くコメント

# ❌ 読めばわかりすぎるコメント
class User:
    # コンストラクタ
    def __init__(self, name: str, email: str):
        self.name = name    # 名前
        self.email = email  # メール

---

パターン⑤：TODO・FIXMEを放置する

# ⚠️ TODOが何ヶ月も放置されているのはNG
# TODO: あとでバリデーション追加する
# FIXME: この計算が正しいか確認する（2年前のコメント）
def calculate_discount(price: int) -> int:
    return price * 0.9

💡 TODOコメントは書くなら必ず期限・担当を明記する

# TODO(Alice, 2026-04-01): バリデーションを追加する

期限のないTODOは永遠に残り続けます。

---

4. ✅ 良いコメントの3パターン

パターン①：「なぜ」を書く

# ❌ 「何を」しているかを書いている（コードを見ればわかる）
# リストを逆順にする
users.reverse()

# ✅ 「なぜ」そうしているかを書く
# 最新のユーザーを先頭に表示するために逆順にする
users.reverse()

# ✅ 「なぜ」の良い例：ビジネスロジックの背景を伝える
# 送料無料の閾値は5000円（2024年4月の価格改定で3000円から変更）
FREE_SHIPPING_THRESHOLD = 5000

# ✅ 「なぜ」の良い例：ハマりやすいバグを防ぐ
# urllibのデフォルトタイムアウトは無限なので明示的に設定する
response = requests.get(url, timeout=30)

# ✅ 「なぜ」の良い例：意図的な処理であることを伝える
# 削除フラグを立てるだけで物理削除しない（監査ログの要件のため）
user.is_deleted = True
db.save(user)

# ✅ 「なぜ」の良い例：諦めたアプローチを記録する（先人の轍を踏ませない！）
# asyncio.run()を使うとJupyter環境でエラーが発生するため、
# 代わりにloop.run_until_complete()を使っています。
# ※ asyncio.run()に戻したくなるかもしれないが、要注意。
loop = asyncio.get_event_loop()
loop.run_until_complete(main())

💡 「諦めたアプローチ」を残すことの価値
「最初はAの方法を試したが〇〇のバグが発生したため、あえてBの方法を採用」
というコメントは、未来のチームメンバーが
「これ、もっとスマートに書けるじゃん！」と変更して同じバグを踏む事故を防ぐ
強力なバリアになります。

---

パターン②：複雑なアルゴリズムの説明

# ✅ 複雑な処理には説明が必要
def calculate_moving_average(data: list[float], window: int) -> list[float]:
    """移動平均を計算する。

    移動平均：直近N個のデータの平均を順番に計算したもの。
    株価チャートや気温の推移など、トレンドを把握するのに使われる。

    Args:
        data: 元のデータリスト
        window: 平均を取る期間（N個）

    Returns:
        移動平均のリスト（長さは data - window + 1）
    """
    result = []
    for i in range(len(data) - window + 1):
        avg = sum(data[i:i + window]) / window
        result.append(avg)
    return result

---

パターン③：外部の制約・仕様への参照

# ✅ 外部の仕様・ドキュメントへの参照
# RFC 5321に従いメールアドレスの最大長は254文字
MAX_EMAIL_LENGTH = 254

# ✅ APIの制限への参照
# GitHub APIのレート制限：認証済みで5000リクエスト/時間
# https://docs.github.com/en/rest/overview/rate-limits
MAX_REQUESTS_PER_HOUR = 5000

---

5. 📖 docstringを書こう

docstringとは？

docstring（ドックストリング）とは、関数・クラス・モジュールの
「仕様書」をコードの中に書いたものです。
help() 関数やIDEのドキュメント表示機能でも参照されます。

Googleスタイルのdocstring（Python）

このシリーズのコード例で一貫して使っているGoogleスタイルです。

def send_email(
    to: str,
    subject: str,
    body: str,
    cc: list[str] | None = None,
) -> bool:
    """メールを送信する。

    SMTPサーバーを経由してメールを送信する。
    送信に失敗した場合はFalseを返す（例外は発生しない）。

    Args:
        to: 送信先メールアドレス
        subject: 件名
        body: 本文
        cc: CCに追加するメールアドレスのリスト（省略可）

    Returns:
        送信成功なら True、失敗なら False

    Raises:
        ValueError: メールアドレスの形式が不正な場合

    Examples:
        >>> send_email("[e-mail]", "件名", "本文")
        True
    """
    ...

docstringの各セクション

セクション	必須	内容
1行サマリー	✅ 必須	関数が何をするか1文で
詳細説明	任意	動作の詳細・注意点など
Args	引数があれば	引数名・説明
Returns	戻り値があれば	戻り値の説明
Raises	例外があれば	発生する例外と条件
Examples	任意	使用例

TypeScriptのJSDoc

/**
 * メールを送信する。
 *
 * SMTPサーバーを経由してメールを送信する。
 * 送信に失敗した場合はfalseを返す。
 *
 * @param to - 送信先メールアドレス
 * @param subject - 件名
 * @param body - 本文
 * @param cc - CCに追加するメールアドレスのリスト（省略可）
 * @returns 送信成功ならtrue、失敗ならfalse
 * @throws {Error} メールアドレスの形式が不正な場合
 *
 * @example
 * ```ts
 * await sendEmail("[e-mail]", "件名", "本文");
 * ```
 */
async function sendEmail(
  to: string,
  subject: string,
  body: string,
  cc?: string[]
): Promise<boolean> {
  ...
}

💡 TypeScriptのJSDocでは型を書かなくていい！
古いJavaScriptのコードでは @param {string} to のように
中括弧で型を指定するスタイルをよく見かけます。
しかしモダンなTypeScriptでは、
VS Codeなどのエディタがコード側の型定義を自動で読み取ってくれるため、
JSDocに型を書く必要はありません。
パラメーター名と説明だけ書けば十分です。
古いコードベースで @param {string} を見かけても慌てないようにしましょう。

docstringに書くべき・書かなくていいこと

書くべきこと	書かなくていいこと
関数の目的・動作の概要	コードを見ればわかること
引数の意味・制約	型情報だけ（型ヒントで十分）
戻り値の意味	実装の詳細（コードを見ればわかる）
発生しうる例外	自明な処理の説明
使い方の例
注意点・副作用

---

6. 🔢 マジックナンバーを排除する

マジックナンバーとは？

マジックナンバーとは、コードの中に突然現れる「意味のわからない数値」のことです。
読んだ人が「この数字って何だっけ？」と思ったらマジックナンバーです。

# ❌ マジックナンバーだらけのコード
def process_order(price: int, quantity: int, user_rank: int) -> int:
    if quantity > 100:          # この100は何？
        price = price * 0.85    # この0.85は何？
    if user_rank >= 3:          # この3は何？
        price = price * 0.95    # この0.95は何？
    tax = price * quantity * 0.10
    if tax > 50000:             # この50000は何？
        tax = 50000
    return price * quantity + tax

# ✅ 定数に意味のある名前をつける
BULK_ORDER_THRESHOLD = 100       # まとめ買い割引の閾値（個）
BULK_DISCOUNT_RATE = 0.85        # まとめ買い割引率（15%引き）
PREMIUM_RANK_THRESHOLD = 3       # プレミアム会員の最低ランク
PREMIUM_DISCOUNT_RATE = 0.95     # プレミアム会員割引率（5%引き）
TAX_RATE = 0.10                  # 消費税率
MAX_TAX_AMOUNT = 50000           # 税額の上限（円）

def process_order(price: int, quantity: int, user_rank: int) -> int:
    """注文の合計金額を計算する。

    Args:
        price: 単価
        quantity: 数量
        user_rank: ユーザーのランク

    Returns:
        税込合計金額
    """
    if quantity > BULK_ORDER_THRESHOLD:
        price = int(price * BULK_DISCOUNT_RATE)
    if user_rank >= PREMIUM_RANK_THRESHOLD:
        price = int(price * PREMIUM_DISCOUNT_RATE)
    tax = min(int(price * quantity * TAX_RATE), MAX_TAX_AMOUNT)
    return price * quantity + tax

マジックナンバーを定数化するメリット

メリット	説明
📖 意味がわかる	0.85 より BULK_DISCOUNT_RATE の方が意図が伝わる
🔧 修正が1か所で済む	税率が変わっても TAX_RATE を1か所直すだけ（DRY原則とも連動）
🔍 検索しやすい	定数名で検索すると使っている場所が全部見つかる

マジックナンバー以外も注意

数値だけでなく文字列のマジックナンバーも要注意です。

# ❌ 文字列のマジックナンバー
if user.role == "admin":        # この "admin" があちこちに散らばると危険
    allow_access()

if order.status == "pending":   # スペルミスに気づきにくい
    send_reminder()

# ✅ 定数または列挙型（Enum）にまとめる
from enum import Enum

class UserRole(Enum):
    """ユーザーのロール。"""
    ADMIN = "admin"
    EDITOR = "editor"
    VIEWER = "viewer"

class OrderStatus(Enum):
    """注文のステータス。"""
    PENDING = "pending"
    PROCESSING = "processing"
    COMPLETED = "completed"

if user.role == UserRole.ADMIN:
    allow_access()

if order.status == OrderStatus.PENDING:
    send_reminder()

💡 Enumにするとタイポをエディタが即座に検出してくれる！

# ❌ 文字列だとタイポに気づきにくい
if user.role == "admn":    # スペルミスでも実行時まで気づかない 😱

# ✅ Enumならタイポした瞬間にエディタが赤線を引いてくれる
if user.role == UserRole.ADIMN:  # 即座にエラーとわかる！ 🎯

文字列をそのまま使うと "admin" を "admn" と書き間違えても
プログラムが動いてしまい、バグの発見が遅れます。
UserRole.ADMIN のように書けばエディタが
「そんなメンバーはない」と即座に教えてくれます。

---

7. 🎯 まとめ

良いコメント vs 悪いコメント

	✅ 良いコメント	❌ 悪いコメント
内容	「なぜ」そうしているか	「何を」しているか（コードの翻訳）
鮮度	コードと一緒に更新される	古くなって嘘をつく
量	必要なところだけ	自明なことにも書く
コード	コードが語る部分はコメントなし	コメントアウトされたコードが残る

docstringのポイント

項目	ポイント
📝 1行サマリー	関数が何をするか1文で簡潔に
📋 Args	引数の意味・制約を書く
🔄 Returns	戻り値が何を意味するか書く
⚠️ Raises	発生しうる例外を書く

マジックナンバーの対処法

対象	対処法
数値	意味のある名前の定数に置き換える
文字列	定数またはEnumにまとめる
複数の関連する値	Enumクラスにまとめる

コメントの黄金ルール：
① コードで「何を」伝え、コメントで「なぜ」を伝える
② コードを変えたらコメントも変える
③ 迷ったら「コメントなしでも読めるコード」を目指す

次回は エラーハンドリング を解説します！
例外処理の基本・エラーメッセージの書き方・
防御的プログラミングの考え方を学びます🌟

💬 質問や感想があれば、コメント欄でお気軽にどうぞ!
👍 役に立ったら、いいね&ストックをお願いします!
🎓 ここまで読んでくださって、本当にありがとうございました!

---

🔗 シリーズ記事

• 【第一回】コードの基本構造
• 【第二回】命名規則
• 【第三回】コードの設計原則
• 【第四回】コメント・ドキュメント（この記事）
• 【第五回】エラーハンドリング（近日公開）
• 【第六回】テスト・ファイル構造・バージョン管理（近日公開）