プログラミング言語のコメントアウトに”XXX”というコメントがあるということをご存知でしょうか


たとえば以下のようなコードがあるということです。

// XXX: なぜうごいているかわからない author 2018/01/12

先日、仕事でプログラムを書いている途中でTODOコメントアウトを残そうとして、「そういえばTODOとかFIXMEコメントの正しい書き方ってあるのか?」という疑問から検索した際に知りました。

プログラムを書く仕事をしていて、たいてい見かけるのが

// TODO hogeする必要あり
// FIXME バグをかかえています

TODOは修正や加筆する時間がなくて書くことが多いです。FIXMEは不具合を調査していて発見した不具合箇所に書くコメントとして時々見かけます。

XXXはこれまでのエンジニア経験上、一度も見かけたことがありません。

XXXの意味としては、「多くの場合動いてしまうが、時々想定外の挙動をする」という、中身がブラックボックスな関数(メソッド)や変数につけられることがあるようです。

だいたいIDE(eclipse,IntelliJ系IDEなど)の機能でハイライトや警告をしてくれたりするので、こうしたコメントアウトの文字列は重要だと個人的に思っています。

要するにXXXがずっとあるまま放置されているとヤバイ

5年ほどWeb系エンジニアとしてホワホワ過ごしていますが、FIXME、TODOコメントは見かけてもXXXを見る機会がなかったのは
XXXコメントが書かれるようなコードはそもそも放置されていたらヤバイからです。

何がヤバイかというと、中身がどう挙動しているか分からないようなメソッドや変数、オブジェクトを使うわけがないからです

自分たちで書いたコードの中にその状態で放置されたメソッドがあったら将来苦労するのは作った本人達なので、早め早めに解明されるなり修正されるなり削除されたりするのです。

ただ、FIXMEやTODOもよく放置されたままになっているものを見かけることはあります。
(前任者が力尽きたか、ドナドナされたか・・・、忘れ去られたか)



なのでコメントアウトのお作法として以下をよく用いるようにしています。

// TODO: 以下の変数名を変える 旅するエンジニア 2018/01/12 

↑の例はTODOの例ですが、IDEによっては「TODO 以下の変数名〜」と書いてもハイライトしてくれなかったりするので一応コロンを入れます。eclipseなど有名どころはこれでハイライトしてくれます。
そしてコメントの後ろに氏名まではいかなくても担当者の姓を書く、また担当者の姓が被ることの配慮も必要だったりします。
職場で発行されたユニークな文字列になるアカウント、コードネームがあればそれにしてもいいかもしれません。

要するに誰が、いつ、何を思ったのかが分かればいい

私はgithub.comアカウントのIDを書くのがクールでナウでヤングだと思っています。

以上、ペーペーで過ごしてきて何も知らないまま育ったエンジニアのメモでした。
(指摘等ありましたらご連絡ください)

参考資料

What does XXX mean in a comment? – softwareengineering.stackchange.com