11-3
命名不足をコメントで補わない
名前から意図が読み取れないメソッドには、意味を再説明するコメントが付きがちだ。しかし呼び出し側に見えるのは名前だけで、コメントは定義元までジャンプしないと読めない。再説明コメントは退化もしやすい。コメントで取り繕う前に、名前そのものをブラッシュアップする。
蔵書管理: 貸出できるかの判定
✕ Bad
check_status という曖昧な名前を、コメントの再説明で延命している。除籍済みの判定が増えたらコメントも直す必要があるが、まず忘れられる
class LibraryBook:
# 紛失・修繕中・除籍・貸出中のいずれでもないとき True を返す。
# True なら貸出手続きに進んでよい
def check_status(self) -> bool:
return not (
Status.LOST in self.statuses
or Status.REPAIRING in self.statuses
or Status.DISCARDED in self.statuses
or Status.LENT in self.statuses
)✓ Good
名前を can_lend に変えれば再説明コメントは丸ごと不要になる。呼び出し側も if book.can_lend(): と読み下せる
class LibraryBook:
UNAVAILABLE_STATUSES = frozenset({
Status.LOST,
Status.REPAIRING,
Status.DISCARDED,
Status.LENT,
})
def can_lend(self) -> bool:
return self.statuses.isdisjoint(self.UNAVAILABLE_STATUSES)コメントは命名の不足を補えない。「コメントを書きたくなったら、まず名前を疑う」を習慣にすると、コメントの総量が減って退化コメントの発生源も減る。