11-2 コードをなぞるだけのコメントは書かない

1行ごとに「何をしているか」を書き起こすコメントは、読めばわかることの繰り返しで理解に貢献しない。それどころか、コードを直すたびにコメントの更新義務が発生し、忘れた瞬間に退化コメントへ変わる。伝言ゲームのように、なぞったつもりで事実と違う説明を書いてしまうリスクもある。

請求書の合計金額の計算

✕ Bad

各行の動作をそのまま日本語にしただけ。情報量はゼロなのに、コードを直すたびにメンテナンス対象が倍になる

挙動をなぞるだけのコメント

def build_invoice_total(items: list[InvoiceItem]) -> Decimal:
    # 小計を0で初期化する
    subtotal = Decimal("0")
    # 明細を1件ずつループする
    for item in items:
        # 単価に数量を掛けて小計に足す
        subtotal += item.unit_price * item.quantity
    # 小計に消費税率を掛けて税額を計算する
    tax = subtotal * TAX_RATE
    # 小計と税額を合計して返す
    return subtotal + tax

✓ Good

なぞりコメントを全部消し、コードから読み取れない会計上の判断（端数処理の位置）だけを残す

残すのはコードが語れないことだけ

def build_invoice_total(items: list[InvoiceItem]) -> Decimal:
    subtotal = sum(
        (item.unit_price * item.quantity for item in items),
        start=Decimal("0"),
    )
    # 消費税の端数処理は請求書単位で1回。
    # 明細ごとに丸めると合計が1円単位でずれる
    tax = (subtotal * TAX_RATE).quantize(Decimal("1"), rounding=ROUND_DOWN)
    return subtotal + tax

「なぜそうしたか」はコードに現れないのでコメントの価値が高く、コードが変わっても古くなりにくい。逆に「何をしているか」はコード自身が常に最新の説明書になっている。

def build_invoice_total(items: list[InvoiceItem]) -> Decimal: # 小計を0で初期化する subtotal = Decimal("0") # 明細を1件ずつループする for item in items: # 単価に数量を掛けて小計に足す subtotal += item.unit_price * item.quantity # 小計に消費税率を掛けて税額を計算する tax = subtotal * TAX_RATE # 小計と税額を合計して返す return subtotal + tax

def build_invoice_total(items: list[InvoiceItem]) -> Decimal: subtotal = sum( (item.unit_price * item.quantity for item in items), start=Decimal("0"), ) # 消費税の端数処理は請求書単位で1回。 # 明細ごとに丸めると合計が1円単位でずれる tax = (subtotal * TAX_RATE).quantize(Decimal("1"), rounding=ROUND_DOWN) return subtotal + tax