11-1 退化コメントを生まない - コーディング原則

コードは仕様変更のたびに書き換えられるが、コメントは置き去りにされやすい。挙動を細かく列挙したコメントは、コードが一歩先に進んだ瞬間に嘘をつきはじめる。これが「退化コメント」で、読み手を誤った理解へ誘導してバグの温床になる。コメントは書き手の意図の劣化コピーでしかないと自覚し、退化しやすい書き方を最初から避ける。

経費精算: 領収書が不要な区分の判定

✕ Bad

「交通費と会議費は領収書不要」とコメントしたが、その後の改定で書籍費が追加され、コメントだけが古いまま嘘をついている

実装と食い違った退化コメント

class ExpenseRule:
    # 交通費と会議費は領収書なしで精算できる
    def needs_receipt(self, expense: Expense) -> bool:
        return expense.category not in (
            Category.TRANSPORT,
            Category.MEETING,
            Category.BOOKS,  # 規程改定で後から追加
        )

✓ Good

対象区分の列挙はコメントではなく、名前を付けた定数としてコードに語らせる。仕様変更時は定数を直すだけで、嘘をつく場所が残らない

列挙はコードに語らせる

class ExpenseRule:
    RECEIPT_EXEMPT_CATEGORIES = frozenset({
        Category.TRANSPORT,
        Category.MEETING,
        Category.BOOKS,
    })

    def needs_receipt(self, expense: Expense) -> bool:
        return expense.category not in self.RECEIPT_EXEMPT_CATEGORIES

ロジックを変更したら同じコミットでコメントも必ず更新する、が大原則。ただしそもそも「挙動の列挙」をコメントに書かなければ、退化のしようがない。コードで表現できる情報はコードに寄せる。

class ExpenseRule: # 交通費と会議費は領収書なしで精算できる def needs_receipt(self, expense: Expense) -> bool: return expense.category not in ( Category.TRANSPORT, Category.MEETING, Category.BOOKS, # 規程改定で後から追加 )

class ExpenseRule: RECEIPT_EXEMPT_CATEGORIES = frozenset({ Category.TRANSPORT, Category.MEETING, Category.BOOKS, }) def needs_receipt(self, expense: Expense) -> bool: return expense.category not in self.RECEIPT_EXEMPT_CATEGORIES