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

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

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

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

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

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

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

よくある問題

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

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

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

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

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

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

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

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

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

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

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

伝える情報を増やす

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

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

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

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

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

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

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

Amazonで詳細を見る

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

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

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

// 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

Amazonで詳細を見る