もっとアノテーションコメントを活用しよう

プログラムのソースを眺めているとときどき目にする TODO などのコメントを、もっと活用しよう、というお話です。

アノテーションコメントとは

アノテーション (annotation) とは注釈という意味です。

アノテーションコメントとは「コメントにメタデータを付加するもの」で、次のような記号が打たれたコメントを指します。

1// TODO: 接続失敗時にリトライする

アノテーションコメントを適切に利用することにより、コメントのみの場合よりもソースの把握や修正すべき点の把握が容易になります。

だからといって「とりあえず TODO つけておこう」という感覚で運用していくと、簡単に破綻します。

特にプロジェクトの初期では大量に TODO がつくことがあますね。
こうなると TODO の数が多すぎて何から手を付けてよいかわからなくなったり、対応しきれなくて燃えてしまうことになりかねません。

まとめると、次のようなケースがよく見受けられます。

これを解消するために、次のことに留意するとずっと良くなりますね。

種類を増やし「表現を増やす」の具体例です。アノテーションコメントには次のようなものが挙げられます。

「TODO という表現が強すぎる」ケースはたくさんあると思います。
MUST なのか、単なるメモに過ぎないのか、プロジェクト内で認識を合わせ、使い分けていくと幸せになれそうです。

意味	説明
TODO	あとで追加すべき不足している機能を記す
XXX	その部分のコードが正しくないが多くの場合動いてしまう
FIXME	修正すべき壊れたコードを記す
OPTIMIZE	パフォーマンスに影響を与える最適化すべき箇所を記す
HACK	リファクタリングすべきコードの臭いのする箇所を記す
REVIEW	レビューすべき箇所を記す
MEMO	なぜこうなったか、といった情報などを記す

後述する参考 URL より引用

MEMO は私が好んで使うものです。
どうしてこれを使うようなったか記憶がないのですが、ソースがおわかりの方はぜひ教えてください。

「温度感やコンテクストがわかるようにすること」の具体例です。

次のような情報を含めることで、わかりやすさはぐっと増しますね。

「修正必須」なのか、「できれば対応したいのか」など、温度感が伝わる内容にすること、チケット番号などを含めるとよりベターでしょう。

なお、コメントに「作者を記す」のは、リーダブルコード で紹介されていたノウハウです。

Dustin Boswell,Trevor Foucher
出版社：オライリージャパン　発売日：2012-06-23

プロジェクトによっては「実装者の名前を残さない」というルールがあるかもしれません。

1// TODO(atuweb): 必須 α1までに対応 計算式未決定 #445 の返答後に修正する

1// XXX(atuweb): バグ #368 の原因と推測される関数 戦うには勇気が必要

1// HACK(atuweb): ライブラリ A のバグ回避のため、やむなくラップして解消

プロジェクトで幸せになるためには議論を通じて文化を育て、運営していくが大切ですよね。

コメントについても「なんとなく」ではなくてちょっとしたルールを整えることでプロジェクトを回しやすくなりますよ、というお話でした。
「もっと良いよー」などありましたらコメントいただけると嬉しいです。

$shibayu36->blog;
最近コード中のTODOコメントの書き方を工夫している http://blog.shibayu36.org/entry/2016/05/08/190000

Qiita
Ruby | アノテーションコメント（TODO、FIXME、OPTIMIZE、HACK、REVIEW）
https://qiita.com/tbpgr/items/1c046a877c6be4d89876

Roy Osherove
出版社：オライリージャパン　発売日：2017-05-13