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

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

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

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

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

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

よくある問題

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

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


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

  • TODO が多すぎて手がつけられない
  • TODO の温度感がわからず、優先度が読み取れない
  • いつの TODO なのかわからない
  • 誰の TODO なのかがわからない

アノテーションコメントのカイゼン案

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

  • TODO だけではなく、表現を増やす
  • 温度感やコンテクストがわかるようにすること

アノテーションコメントの例

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

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

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

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

伝える情報を増やす

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

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

  • 誰が
  • なぜ
  • なんのために
  • いつまでに

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


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

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

アノテーションコメントのサンプル

1// TODO(atuweb): 必須 α1までに対応 計算式未決定 #445 の返答後に修正する
1// XXX(atuweb): バグ #368 の原因と推測される関数 戦うには勇気が必要
1// HACK(atuweb): ライブラリ A のバグ回避のためやむなくラップして解消

おわりに

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

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

[プログラミング]そのコメント、カッコ悪い
atuweb.net

参考

$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

Amazonで詳細を見る

この記事の著者 Webrow (うぇぶろう)
Web アプリ開発、 Web 顧問 エンジニア、WordPress サポートいたします。