プログラムのソースを眺めているとときどき目にする TODO などのコメントを、もっと活用しよう、というお話です。
アノテーションコメントとは
アノテーション (annotation) とは 注釈 という意味です。
アノテーションコメントとは「コメントにメタデータを付加するもの」で、次のような記号が打たれたコメントを指します。
// TODO: 接続失敗時にリトライするアノテーションコメントを適切に利用することにより、コメントのみの場合よりもソースの把握や修正すべき点の把握が容易になります。
よくある問題
だからといって「とりあえず TODO つけておこう」という感覚で運用していくと、簡単に破綻します。
特にプロジェクトの初期では大量に TODO がつくことがあますね。
こうなると TODO の数が多すぎて何から手を付けてよいかわからなくなったり、対応しきれなくて燃えてしまうことになりかねません。
まとめると、次のようなケースがよく見受けられます。
- TODO が多すぎて手がつけられない
- TODO の温度感がわからず、優先度が読み取れない
- いつの TODO なのかわからない
- 誰の TODO なのかがわからない
アノテーションコメントのカイゼン案
これを解消するために、次のことに留意するとずっと良くなりますね。
- TODO だけではなく、表現を増やす
- 温度感やコンテクストがわかるようにすること
アノテーションコメントの例
種類を増やし「表現を増やす」の具体例です。 アノテーションコメントには次のようなものが挙げられます。
「TODO という表現が強すぎる」ケースはたくさんあると思います。
MUST なのか、単なるメモに過ぎないのか、プロジェクト内で認識を合わせ、使い分けていくと幸せになれそうです。
| 意味 | 説明 |
|---|---|
| TODO | あとで追加すべき不足している機能を記す |
| XXX | その部分のコードが正しくないが多くの場合動いてしまう |
| FIXME | 修正すべき壊れたコードを記す |
| OPTIMIZE | パフォーマンスに影響を与える最適化すべき箇所を記す |
| HACK | リファクタリングすべきコードの臭いのする箇所を記す |
| REVIEW | レビューすべき箇所を記す |
| MEMO | なぜこうなったか、といった情報などを記す |
MEMO は私が好んで使うものです。
どうしてこれを使うようなったか記憶がないのですが、ソースがおわかりの方はぜひ教えてください。
伝える情報を増やす
「温度感やコンテクストがわかるようにすること」の具体例です。
次のような情報を含めることで、わかりやすさはぐっと増しますね。
- 誰が
- なぜ
- なんのために
- いつまでに
「修正必須」なのか、「できれば対応したいのか」など、温度感が伝わる内容にすること、チケット番号などを含めるとよりベターでしょう。
なお、コメントに「作者を記す」のは、リーダブルコード で紹介されていたノウハウです。
リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック (Theory in practice)
Dustin Boswell,Trevor Foucher
出版社：オライリージャパン
発売日：2012-06-23
アノテーションコメントのサンプル
// TODO(atuweb): 必須 α1までに対応 計算式未決定 #445 の返答後に修正する// XXX(atuweb): バグ #368 の原因と推測される関数 戦うには勇気が必要// HACK(atuweb): ライブラリ A のバグ回避のため、やむなくラップして解消おわりに
プロジェクトで幸せになるためには議論を通じて文化を育て、運営していくが大切ですよね。
コメントについても「なんとなく」ではなくてちょっとしたルールを整えることでプロジェクトを回しやすくなりますよ、というお話でした。
「もっと良いよー」などありましたらコメントいただけると嬉しいです。
この記事は tomita@atuweb がお届けしました。
参考
$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
