【リーダブルコード】コメントに書くべきこと
※ 下記のリンクにある本の韓国語版を読んで簡単に整理しました。
コメントに書くべきこと
コードからすぐに推測できることをコメントに書いてはいけない。
これまでコメントを書く習慣はあまりなかった。というのも、コードを見ればだいたい理解できると感じていたからだ。
しかし、そのコードを初めて読む第三者の立場に立ってみると、全体像を把握するのは決して簡単ではない。
この章を読んで、コメントの意義について改めて考える機会になった。
❌ 悪い名前にコメントをつけるな – 名前を直した方が早い
良いコードであれば、コメントがなくても理解できる。
変数名や関数名が適切であれば、その役割は自然と伝わるからだ。
とはいえ、本当に良い名前をつけるのは常に難しい。それでも、コメントで補うよりは、名前を改善する方が建設的だと感じた。
コメントで「コードがよくない理由」を正直に残す
// このクラスはどんどんひどくなっている。
// おそらく ResourceNode のサブクラスを作って整理すべきだ。
こういったコメントは、今のコードが問題を抱えていることを素直に示すものだ。
そして、後からコードに触れる人へのヒントにもなる。
もし何も書かれていなければ、誰もそのコードに手をつけたがらなくなるかもしれない。
「綺麗なコードにだけコメントを書くべき」と思っていたが、実際は汚いコードこそコメントが必要なのだと思い知らされた。
弱点は隠すものではなく、受け入れて言葉にするべきだ。誰よりも状況を理解しているのは、今それを書いている自分自身なのだから。
コメントの目印
| タグ | 意味 |
|---|---|
TODO: |
やるべきこと |
FIXME: |
不具合があるコード |
HACK: |
美しくない回避策 |
XXX: |
危険！重大な問題がある箇所 |
今までは TODO くらいしか知らなかったが、こうした目印は想像以上に便利に使えると感じた。
関数内での処理の要約としてのコメント
public void generateUserReport() {
// ユーザー用のロックを取得する
...
// データベースからユーザー情報を読み取る
...
// 情報をファイルに書き込む
...
// ユーザー用のロックを解放する
...
}
普段であれば、インデントや関数分割で構造を整えるだけで済ませるかもしれない。
でもこのようにコメントで「何をする処理か」を明示しておくと、読み手は詳細を読む前に概要をつかむことができる。
変数名や関数名がどれほど良くても、全体の流れはコメントの方が瞬時に伝わることもある。
第5章の感想
この章では、良いコメントとは何かについて、実例と共に語られていた。
「コメントを書くことに躊躇したなら、思い浮かんだことをまず書いてみよう。
たとえ、それがまだ整理されていない思いつきだったとしても。」
コメントを書くことにためらいがちな理由は、「うまく書けないかもしれない」という不安だと思う。
でも、完璧な説明でなくても、素直なメモが将来の自分や他人を助けることは多い。
コメントを書くには以下のような視点が必要になる：
- 今の関数がどんな機能を持っているのか
- どんな値を使い、どんな変化を起こすのか
- 将来的にどう改善・分離すべきか
そうした情報を意識して書くことで、保守性と可読性の高いコードに近づいていけるはずだ。
これからはコメントを書くことにもっと積極的になろうと思えた章だった。
Discussion