L01 ch04 — コメントと docstring

L01 ch04 — コメントと docstring

「未来の自分」と「他人」が読めるコードを書く最小単位

ゴール

• 行コメント # の使い方を理解する
• docstring ("""...""") で関数の意図を残せる
• 「何を」ではなく「なぜ」をコメントに書ける

行コメント #

# 消費税率 (2026 年時点)
TAX_RATE = 0.10

price = 1000
total = price * (1 + TAX_RATE)  # 税込み価格
print(total)

• # から行末までが Python に無視される
• インライン (code # comment) も可

docstring とは

関数・クラス・モジュールの先頭に書く 三重引用符の文字列。

def greet(name: str) -> str:
    """名前を受け取って挨拶文を返す"""
    return f"Hello, {name}"

• 単なる文字列だが、help() / IDE / FastAPI の自動 docs に拾われる
• コメント (#) と違って オブジェクトとして残る (greet.__doc__)

複数行 docstring

def calc_tax(price: int, rate: float = 0.10) -> int:
    """税込み価格を計算する

    Args:
        price: 税抜き価格
        rate: 税率 (デフォルト 0.10)

    Returns:
        税込み価格 (int に丸める)
    """
    return int(price * (1 + rate))

• 1 行目: 要約
• 空行
• 詳細 (引数・戻り値・例外)

FastAPI との接続

@app.get("/users/{user_id}")
def get_user(user_id: int):
    """ユーザー ID からユーザー情報を取得する"""
    return {"id": user_id}

→ FastAPI が docstring を 自動生成 docs (/docs) の説明欄に表示する。

コメントを書くだけで API ドキュメントになる。

「何を」ではなく「なぜ」

# ❌ 悪いコメント (コードを読めばわかる)
x = x + 1  # x に 1 を足す

# ✅ 良いコメント (理由・背景)
x = x + 1  # 0-indexed を 1-indexed に変換 (UI 表示用)

コメントは コードに書けない情報 (理由・制約・将来 TODO) を残す場所。

よくある間違い

# ❌ docstring を関数の外に書く
"""この関数は挨拶する"""  # ただの文字列リテラル (無視される)
def greet():
    return "Hello"

# ✅ 関数の中の 1 行目に置く
def greet():
    """挨拶する"""
    return "Hello"

drill

drill/ — 関数の docstring を完成させる

拡張課題

1. help() で確認: 自作関数を help(greet) で表示し docstring が出ることを確認

   help(greet)
   # → greet(name: str) -> str
   #     名前を受け取って挨拶文を返す
   

1. TODO コメント: # TODO: バリデーション追加 と書いておくと IDE が一覧化してくれる

1. モジュール docstring: ファイルの先頭 (import より前) に """このモジュールは...""" と書ける

よくある詰まり

次に学ぶ領域