読者です 読者をやめる 読者になる 読者になる

プログラムコメントはもっと書かないべき

「プログラムコメントはたくさん書くべき」の方が一般的かもしれませんが、リスクも考えましょう。この記事はプログラムコメントを極力書かないようにしている私のスタンスをまとめてみました。

プログラムコメントのリスクを考えると、書かない方がいい

私はプログラムコメントがリスクの方が高くあまり意味が無いと思うようになってから、なるべく書かないようにしている。例えば次のようなリスクがある。

  • コメントがメンテされず、コードと乖離してしまう
  • 書くこともないのにやっつけで書いてしまいただのノイズになる

「コメントがメンテされず、コードと乖離してしまう」については、他人の作成したコードを改修作業したことがある人なら理解できると思うが、コードを改修するとしてもそのコメントの方が改修しづらい。今行っている改修がこのコメントにどう影響しているのかが判断しづらいので、コメントは放っておきたくなる。そんなことを重ねていると、コメントとコードが乖離してしまってとても困った状況になっていく。

また「 書くこともないのにやっつけで書いてしまいただのノイズになる」もよくある。プロジェクトの決まり事でとりあえずかくとこんな感じになる。

/**
 * 口座クラス
 */
public class Account {
    …
}

クラス名をみればわかることをわざわざ日本語にしても仕方ない。ほんとにこれだけなら書かない方がいいのに、決まりだから書いたりすることがある。

このように考えていくと、プログラムコメントはとてもリスクが高くて意味の無いことが多いことに気がつく。

プログラミングでコメント機能を最初に教わるときに、こういったリスクの説明をおそらくされない。むしろ講師の人は「コメントはなるべく書きましょう」という言い方をする方が多い。それをずっと引きずる人が多いので、コメントをたくさん書きましょうという風潮になっている気がする。ただよく考えると、そんなにウェルカムなものでもない。リスクを考えるべきである。

コメントを書くより「コードを直す」を優先すべき

私はコメントを書きたくなってしまったら「コードを直す」ことを考えるようにしている。

コメントを書こうとしているときは「このコードでは他の人に伝わらないかもしれない」と考えているということなので、根本としてはコードが悪い状態なはず。なのでコメントに頼らないコードにすることを第1に考える。これはその状況になったときだけ考えるのではなく、常日頃から考えているし、考えておかないといけない。

コメントを書くぐらいだったら、ドキュメントを書く

コメントでは直近のコードの説明以外にも、全体像の説明であったり仕様の説明であったりを書きたくなることがある。ただこれはそもそもコメントに書くべき事ではない。ドキュメントにすべきことである。

ただドキュメントにしたところで、ドキュメントがメンテされないとコードと乖離してコメントと同じ問題を抱えてしまう。私はこの問題を「ドキュメントはそのとき(作成時時点)の考えのスナップショットとする」という考え方で対処している。時間が経ちすぎていれば参考にしないし、必要な物は何度も作り直すので、更新される。本当に更新され続けるのはほんの一部にしておけば、負担も少ない。

とはいえ、コメントを書くことはある

ここまでの書いたとおり私はコメントを極力書かないようにしているが、次の場合はコメントを書くことがある。

  • 言語の勉強

新しい言語や久しぶりに使う言語の場合はコメントを書きながら勉強することがあるし、ブログなどでコードを説明する場合には使う。

コメントを極力書かないスタンスの人が、どの場面はコメントを書くべきかはまだ研究中。

リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック (Theory in practice)

リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック (Theory in practice)

  • 作者: Dustin Boswell,Trevor Foucher,須藤功平,角征典
  • 出版社/メーカー: オライリージャパン
  • 発売日: 2012/06/23
  • メディア: 単行本(ソフトカバー)
  • 購入: 68人 クリック: 1,802回
  • この商品を含むブログ (137件) を見る