アノテーションコメント (TODO・FIXME・XXX) を使う

Java における JavaDoc コメントや、JavaScript における JSDoc のようなドキュメンテーションコメントは、IDE でツールチップ表示できたりとか、後で API 仕様書を HTML 生成出来たりとかするので、ちゃんと書きましょうという話はよく見かけるだろう。

しかし、「TODO コメント」などのアノテーションコメントとなると、その概念自体を知らない人が案外多い。アノテーションコメントはその名のとおり、「注釈」をコメントで入れる手法で、最近の IDE は代表的なアノテーションコメントをハイライトしてくれたりする。代表的なのは以下あたりだろう。

TODO … 後で追加・変更が必要なコード
FIXME … リファクタリングや不具合修正して欲しいコード
XXX … HACK とも。危険なコード、なぜ動いているか分からないようなコード

といったアノテーションだ。

function calcPrice(item) {
  // TODO : 現状はダミーデータを返しているだけ・あとで実装すること
  return 100;
}

function mergeItems(items1, items2) {
  // FIXME : 引数が null の時に例外が発生するので入力チェックをした方が良い
  return ...;
}

こんな感じで、プログラミング言語に限らず、TODO : とか FIXME : とかいう接頭辞を付けてコメントを書くのだ。

このようなルールでコメントを入れていけば、プロジェクト全体のコードを grep するだけで問題箇所が明らかになる。逆にいえば、grep してもこうしたアノテーションコメントが出てこなくなったら、綺麗で完成されたコードになっている、といえるワケだ。

人によって色んなアノテーションを使うと、検索容易性・ググラビリティが下がり、grep 漏れしかねないので、どのアノテーションを使うか迷ったら TODO : で書く、としておくと良いだろう。

そもそもコメントを書くのをサボる輩が多くてゲンナリする。一目見て分かるようなコードを書いてない癖に、説明責任を放棄しやがって。分かりにくいところがあったらコメントだけでも追記するとか、まずコメントをたくさん書く文化が出来てほしいモノだ。