ホーム

【リーダブルコードから学ぶ】コメントの残し方

導入

新人プログラマー読むべき本として良くあげられる「リーダブルコード」を読みました。
そこでソースコードにコメントを残す際に気をつけるべき点についてとても参考になりましたので要点をまとめます。

この記事を読んでわかること

  • ソースコードへのコメントの残し方
  • リーダブルコードの感想

目次

  1. ソースコードにどのようなコメントを書くべきか

    1. コメントするべきではないこと
    2. TODOコメントをつける
    3. 読み手の立場になって考える
    4. ライダースブロック
    5. WHAT・WHY・HOWをコメントすべきか
  2. 感想

ソースコードにどのようなコメントを書くべきか

個人で開発する分にはあまり気になりませんが、チームで開発する上では、ソースコードにコメントを残すことはとても大切です。
※コメントの無いソースコードを読むことは苦痛でしかありません・・・

コメントの目的は「コードの動作を説明すること」だけではない、とありました。

コメントするべきではないこと

最初に考えるのは「何をコメントすべきでないか」です。
コメントは残すべきですが、むやみに残すべきではありません。
例えば以下のソースをみてください。

// Personクラスの定義
public class Person {
  // コンストラクタ
  Person();
}

クラス定義とコンストラクタ定義に対してコメントを記載していますが、このコメントには意味がありません。
javaがわかる人であれば、コードを読めば「Personというクラスが定義されていること」、「コンストラクタが定義されていること」は理解できますので、わざわざ書く必要はありません。
※ピンとこなければ、それはソースコードのせいではありません。javaがわかっていないだけですので別問題です。  

しかし、プログラマの世界では以下の構図となるそうです。

「優れたコード > ひどいコード + 優れたコメント」

ソースコードを見ただけで機能がわかるようになれば理想ですね。
※実際は業務的な都合でなかなか上手くいきませんが・・・

TODOコメントをつける

次は「何をコメントすべきか」を考えます。   例えばある機能を開発していて、「あれも実装しなければ・・・これも実装しなければ・・・」となることは多々あります。
しかし、それをExcel等で管理するのはエンジニアにとってストレスです。
そんなときは以下のようにTODOコメントを残すべきです。

//TODO: 値をキャッシュしてパフォーマンスをあげる

上記のように実装したい箇所にコメントを残しておけば、他のエンジニアに作業を依頼する場合でも共有しやすいです。
別タスクとして切り出しておくことで管理もしやすくなります。

このようなコメントをアノテーションコメントと言います。
他にもいくつかありますので、チームで利用をルール化しておくと開発効率が上がるはずです!
TODO: 以外のアノテーションコメントをまとめた

読み手の立場になって考える

新規にプロジェクトに参画した人がソースコードを読んだときに疑問に思うであろう箇所については、コメントを残すべきです。
以下は私が実際の現場で遭遇したケースをもとに記載します。
例えば過去の設計のせいで、意図しないところにダミーデータが入っており、そのチェック処理を実装しなければいけないとします。
この場合は、以下のようなコメントを残しておくべきです。

// XXシステムとの連携対応のため、Userテーブルから取得したメールアドレスにはダミーデータが入っていることがあるため、チェック処理を行う
if (email == "dummy@dummy.com") {
  ・・・
}

事情を知っている人であればソースコードを読めば意図が伝わるでしょうが、これからそのシステムに関わる人にとっては意味不明です。
コメント一つあるだけで、読み手が無駄に考える時間を減らすことができます。

ライダースブロック

プログラマーはコメントを書きたがりませんが、行き詰まってしまって文章が書けないことをライダースブロックというそうです。
コメントを上手く書くことは大変なので、めんどくさがって残さない人も多いです。

何もコメントを残さないより、曖昧でも何かコメントを残すべきです。

例えば前述した例の場合だと、以下のコメントでも無いよりましです。

//たまにダミーデータが入ってるから注意
if (email == "dummy@dummy.com") {
  ・・・
}

これをもっと詳細なコメントにしていけば良いのです。

  • 変数emailの値はどこから取得しているのか
  • なぜダミーデータが入りうるのか

といった点を考えていくと、当初のようなコメントになります。
最初から完璧を求めるのではなく、拙くても書き始めて見ることが大切です。

WHAT・WHY・HOWをコメントすべきか

「コメントにはWHATではなくWHYを書こう」とアドバイスする人がいるらしいです(私は会ったことありませんが)
本書としては「WHATでもHOWでもWHYでも、役に立つものなら何でも書こう」とアドバイスしています。
何も無いよりマシなのです。

感想

エンジニアになって3年目に読みましたが、日頃当たり前に考えていることを見直す機会になりました。
実際の現場でも一度はレビューで指摘されることがたくさん書かれていますので参考になるかと思います。

1点注意ですが、本書のサンプルにはC言語やjavaの話が出てきます。
毛嫌いする方もいるかと思いますが、それが本質では無いのでさらっと読んでみるのがおすすめです。

本日はリーダブルコードのコメントの残し方について、簡単にまとめました。
他の章も参考になりますので、ぜひ手にとってみてください!