TODOコメントってあんまり意味がないんじゃないか説

とりあえず書き込まれるTODO

ある日のことです。新機能開発のためにコードを眺めていると該当箇所に対応するテストコードが全くないことに気づきました。「TDDでやってるのになぁ」と思っていると、テストコードのファイルだけが作られていて、中にTODOコメントで想定されうる全てのパターンが記載されていました。

その数も中々のもので、ファイル内でTODOを検索してみると40件近く、TODOが書き込まれていることに気づきました。「〜したい」「〜の場合どうするか」という誰かが残したであろうTODOコメントが各所に溢れていました。

TODOコメントがあって、後に何かをやる必要がある、やってほしいというのは分かるのですが、それがいつ発生した問題で、どのように解決するのか、他に関連する箇所はないのか、今は問題となり得るのか...と考えることがたくさんあります。

しかしながら、ただTODOと記述がされていても、上記の情報を得ることは難しいです。コメントを記載した人が詳細を覚えていればラッキーですが、そうでなければ何をしていいのか分からないコードに残された永遠のTODOとなってしまいます。

TODOという名前のくせに永遠にDOされることはないのです。

＿人人人人人人人＿
＞　永遠のTODO　＜
￣Y^Y^Y^Y^Y^Y^Y^￣

generated: ＞突然の死＜ジェネレーター

使うのは問題ないと思いますし、動作に影響を与えるものでもありません。また実装時間というのもプロジェクトによっては大きく制限もあるかなと思います。しかし、ただTODOを書くだけでは、何が問題で何が重要なのか、いつまでにやる必要があるのか...など伝えられる情報が限られてしまいます。

なのでTODOコメントを使う場合はチームでフォーマットを定義しておくのが良いのではないでしょうか。自分はこんな感じでTODOコメントを書くようにしています。

# TODO: 2021/05/31 -> 来月まで
# validationが弱い。空白文字が入っているとそのまま登録されてしまうのでtrimする。

どうでしょうか。記載日と記載時に想定した締め日を1行目に書いてあげて、2行目に何が問題で何をすればいいのか書いておきます。
改めて記事にしてみて思ったのですが、TODOに優先順位が付けられるように情報が添付されているという状態が望ましいかなと感じました。

参考になればと思います。

プログラマが知るべき97のこと