11-4 「なぜ」と注意点を書く（docstring）

コードが読まれる機会のほとんどは保守と仕様変更のとき。保守する人は「どういう意図のロジックか」を、変更する人は「どこに注意すれば安全か」を知りたがっている。コメントにはこの2つ、つまり意図と注意点を書く。公開する関数には docstring で引数・戻り値・例外まで形式的に残すと、IDE やドキュメント生成からも参照できる。

01 仕訳帳の並び順: 同じコードでもコメントの価値が違う

✕ Bad

ソートしていることはコードを見ればわかる。挙動の説明では、変更する人の役に立たない

「何をしているか」しか書いていない

class JournalBook:
    def rows_for_display(self) -> list[JournalRow]:
        # 日付と伝票番号でソートして返す
        return sorted(self._rows, key=lambda r: (r.date, r.entry_no))

✓ Good

コードは同じでも、「なぜこの順序か」「変更時に誰へ確認すべきか」を書けば、将来の変更者を事故から守れる

意図と仕様変更時の注意点を書く

class JournalBook:
    def rows_for_display(self) -> list[JournalRow]:
        # この並び順は監査時の証憑突合の前提になっている。
        # ソートキーを変える場合は監査対応の担当に確認すること
        return sorted(self._rows, key=lambda r: (r.date, r.entry_no))

02 源泉徴収税額の計算を docstring で説明する

✓ Good

引数・戻り値・例外をフォーマットに沿って記述する。呼び出し側のエディタ上でポップアップ表示され、定義元へ飛ばなくても使い方がわかる

Google スタイルの docstring

def withholding_tax(fee: Decimal) -> Decimal:
    """個人への報酬にかかる源泉徴収税額を計算する。

    Args:
        fee: 税抜の報酬額（円）

    Returns:
        源泉徴収税額。1円未満は切り捨て

    Raises:
        ValueError: fee が負の場合
    """
    if fee < 0:
        raise ValueError("報酬額には0以上を指定してください")
    rate_low, rate_high = Decimal("0.1021"), Decimal("0.2042")
    base = min(fee, MILLION) * rate_low
    over = max(fee - MILLION, 0) * rate_high
    return (base + over).quantize(Decimal("1"), rounding=ROUND_DOWN)

Java の Javadoc に相当するのが Python では docstring。help() や IDE のホバー表示、Sphinx による API ドキュメント自動生成が docstring を読む。書式は Google スタイル・NumPy スタイル・reST のいずれかにプロジェクトで統一する。

class JournalBook: def rows_for_display(self) -> list[JournalRow]: # この並び順は監査時の証憑突合の前提になっている。 # ソートキーを変える場合は監査対応の担当に確認すること return sorted(self._rows, key=lambda r: (r.date, r.entry_no))

def withholding_tax(fee: Decimal) -> Decimal: """個人への報酬にかかる源泉徴収税額を計算する。 Args: fee: 税抜の報酬額（円） Returns: 源泉徴収税額。1円未満は切り捨て Raises: ValueError: fee が負の場合 """ if fee < 0: raise ValueError("報酬額には0以上を指定してください") rate_low, rate_high = Decimal("0.1021"), Decimal("0.2042") base = min(fee, MILLION) * rate_low over = max(fee - MILLION, 0) * rate_high return (base + over).quantize(Decimal("1"), rounding=ROUND_DOWN)