細かいコメントは書きすぎない方がいい？？
はじめに
コメントは少なければ少ないほどいい。
— 『Good Code, Bad Code』より
「え、コメントを書かなくていいの!?」
プログラミングを始めたばかりの頃、私はドキュメント至上主義でした。関数1つ書くたびに日本語で説明を付け、引数ごとにコメントを足し……気づけばソースよりコメントが長いコードの完成。
でも実務を1年ほど経験した今、ようやく本書の主張が腑に落ちてきました。結論から言うと “コメントを読まなくても理解できるコード” を書いた方が、チームも未来の自分もハッピーになれます。
この記事では『Good Code, Bad Code』のエッセンスと私の実体験を交えながら、初学者向けに「コメント最小主義」の考え方をまとめます。
TL;DR（3行まとめ）
- コメントは“最後の手段”：まずは命名や設計で伝える。
- 人は細かい文字を読まない：使う側が絶対に見るのは関数名・引数・戻り値だけ。
- 制限で守る：想定外の使い方はコンパイルエラー／例外で防ごう。
なぜコメントは読まれないのか？
契約書メタファ
『Good Code, Bad Code』ではスクーターのレンタルサービスを例にこう語られています。
| 明確だから読むもの | 不明瞭だから読まれないもの |
|---|---|
| 料金 / 借りる場所 / 返却場所 | 長〜い利用規約の細かい条項 |
私たちは「1時間いくら？ どこで借りてどこで返す？」のような必須情報には必ず目を通します。しかし利用規約に潜む“30 km/h以上で走ると壊れます。壊したら弁償300ドル”の一文まで丁寧に読む人はほとんどいないでしょう。これでは多くの怠惰なユーザー（私も含む）は困ってしまいます...
コードに置き換えると…
| “必ず見る”明確なもの | “読まれにくい”不明瞭なもの |
|---|---|
|
関数名 / クラス名 引数 / 戻り値 |
コメント 例外処理 |
つまり、コメントは規約の細則に等しいというわけです。読まれない前提で設計しないと、バグの温床になります。
コメントを減らす3つの作戦
1. 意味が一目で分かる命名
# Bad
def proc(dt): ...
# Good
def send_daily_report(date: datetime): ...
「名前を読めば用途が分かる」を徹底すれば説明文は要りません。
2. 一般的な実装パターンを使う
- Python らしいイテレータ
- REST らしい URL 設計
- React らしいフック命名
読者が“見慣れた形”ならドキュメントは最低限で済みます。
3. 制限をコードで enforce する
@dataclass(frozen=True)
class KmPerHour:
value: int
def __post_init__(self):
if self.value > 30:
raise ValueError("30km/h を超える速度は許可されていません 🚫")
「30 km/h以上を禁止する」ロジックを型や例外で表現すれば、規約に埋もれることもありません。
スクーターの例をコードに当てはめる
コード上でユーザーに何かを守らせたい場合は、そもそもできないようにすれば良い話。
先ほどのスクーターの例も、そもそも30km/h以上出ないようにすれば問題ないわけです。
def rent_scooter(*, duration_h: int, speed_limit: int = 30) -> None:
"""
スクーターをレンタルする
Parameters
----------
duration_h : int
レンタル時間（時間単位）
speed_limit : int, optional
速度上限 (km/h)。デフォルト 30。
"""
if speed_limit > 30:
raise ValueError("Speed limit must be <= 30 km/h")
...
- 速度上限は引数名で主張。
- 上限違反はコメントではなく例外で防止。
これならドキュメントを読まなくても安全に使えますよね。
まとめ
コメントは “補足” ではなく “最後の砦”。
まずは命名・設計・制限で「読まなくても分かる／壊れない」コードにしよう。
もちろん「なぜそう実装したのか」「ドメイン特有の知識」などはコメントに残す価値があります。しかしそれでも最小限で OK。
明日読む自分と、まだ顔も知らない未来の仲間のために——読まれなくても機能するコードを目指してみませんか？
参考文献
-
Sarah Drasner, “Good Code, Bad Code”
（日本語訳未発売／英語版は各種オンライン書店で購入可能）
Discussion