データ戦略部*1でエンジニアをしています、22新卒の金子です。
突然ですが、皆さんはコードにアノテーションコメントを使っていますか？アノテーションコメントというのはTODO、FIXME、NOTEなど、コメントに何かしらのプレフィックスを付けて、コメントの意図、性質を分かりやすくするというものです。
今回の記事では、その中でも最もよく使われるであろう、TODOコメントとの向き合い方について考えたいと思います。
TODOコメントの問題点
何の気なしにTODOコメントを使っていると、以下のような問題が生じます。
- 数カ月前に書かれたTODOコメントが未対応のまま放置されている。
- 対応済みのTODOコメントが消されていない。
- メンバーによってTODOコメントの温度感が違う。
このような理由から、TODOコメントは増加の一途をたどります。私の所属するプロジェクトはまだ発足から日が浅く、古くとも数カ月前のコメントですが、プロジェクトによっては年単位で放置されているTODOコメントもあることでしょう。コメントはコードの動作に何ら影響を与えないため、これらの問題点は得てして軽視されがちです。しかし、本来はプログラマに有用な情報を与えるべきコメントが、逆にプログラマを困惑させるようでは本末転倒です。
そこで、TODOコメントにも運用が必要となるわけです。
やったこと
ここからは、私のチームで実際にどのようにTODOコメントを運用するようにしたのかを紹介します。
1. TODOコメントの基準を決定する。
まず初めに、チームでTODOコメントを付ける際の基準を決める必要があります。ここで重要なのは、具体的な基準を設けることです。「緊急度の高いもの」や「数日以内に対応すべきもの」といった漠然とした基準ではあまり意味がありません。例えば「チケットに紐づける」であったり、「対応期日を併記する」だったり、具体的な基準を設けます。
私のチームではプロジェクト管理にJiraを使用しているため、「Jiraのチケットに紐づけること」を基準としました。Jiraのチケットに紐づかないTODOコメントは書かないことを決定します。
2. TODOコメントを棚卸する。
次に、既存のTODOコメントを棚卸します。ここで必要なのは、TODOコメントを一覧できるようにするツールです。私のチームではVSCodeを使用しているため、Todo Tree という拡張機能を使用することにしました。
この拡張機能を使い、チームで時間を取ってTODOコメントを一件一件確認していきました。私のチームでは15分程度時間を取ることで終わりましたが、大規模なプロジェクトでは何回かに分けて行う必要があるかもしれません。
棚卸作業では大きく分けて以下のパターンがありました。
- 未対応だがチケットが存在する → コメントにそのチケットの番号を追記する
- 未対応でチケットも存在しない → チケットを作り、コメントにそのチケットの番号を追記する。
- 対応済み → 削除
- チケットに起こすには軽微なもの → 他のプレフィックスコメントを使用する。
ここで重要なのは最後のパターンです。最初に「TODOコメントはチケットに紐づける」と指標を決めましたが、既存のTODOコメントの中にはこの温度感に見合わない、チケットに起こすまでもない軽微なものが存在しました。例えば、「anyを使っている箇所でしっかり型を定義したい」など、機能やパフォーマンスに特に影響を与えるわけでもない箇所です。
こうした、チケットに起こすには軽微な修正はFIXMEコメントを使用することにしました。
3 仕組み化
さて、ここまでTODOコメントの基準の決定、棚卸を行いました。しかし、現時点では「TODOコメントはJiraのチケットに紐づけること」というのは単なる取り決め以上の意味を持ちません。このような決定を行っても強制する仕組みがなければ、月日が経つうちに、メンバーが増えるうちに形骸化していくことでしょう。そこで、この決定を基に「チケットの番号が書かれていないTODOコメントがあるとエラーになる」仕組みを作ります。
私のチームではTypeScriptを使用しているため、ESLintのルールとして定義することにしました。eslint-plugin-todo-plz というプラグインを使い、正規表現でTODOコメントの形式を指定します。
"todo-plz/ticket-ref": ["error", { "commentPattern": "TODO:.*YOD-[0-9]+.*" }]
こうすることで、TODOコメントの形式を「TODO:」から始まり、「YOD-123」のようなチケット番号を含む、と定義することができます。CIでESLintを走らせれば、この形式に合わないコメントがあった場合にCIが落ちるようにすることができます。
Q. 他のアノテーションコメントは？
TODOコメントはチケットに紐付け、チケットに起こすまでもない軽微な修正はFIXMEにするという方針を決定しました。しかし、アノテーションコメントはこれ以外にもHACKやNOTEなど多くの種類が存在します。チームで話し合った結果、その他のコメントについては各自の判断で自由につけて良いこととしました。理由は主に以下の２つです。
- 他のアノテーションコメントはTODOやFIXMEなどと違い、「やるべきこと」や「したいこと」を示さず、タスク管理上の障害にならないため。
- 厳格にルールを設けすぎて気軽にアノテーションコメントを使えなくなることの弊害が大きいと思われるため。
ここで行いたいのは、有象無象のTODOコメントがコード中に散らばり、もはやアノテーションコメントとして意味をなさなくなるのを防止することです。厳格なルールを設けて、本来はコードを読む際の有用な道案内人となるべきアノテーションコメントを残すのを萎縮してしまうようでは本末転倒です。よって、他のアノテーションコメントについては特に明確な基準を設けず、メンバーがつけたいと思った時につけるという方針にしています。これで特定のアノテーションが濫用されたりしては問題ですが、現状はこの方針で特に問題は起こっていません。
まとめ、今後の展望
ここまでで無秩序なTODOコメントをコードベースから一掃し、さらに今後はそのような事態が起こらないようにする仕組み作りが完了しました。これでTODOコメントは本来の役割を取り戻し、プログラマにいつ、いかなる時に何をすべきかという天啓を与えてくれることでしょう。しかし、対応が完了したチケットのコメントが放置されてしまわないか、今度はFIXMEコメントが増殖してしまわないかなど、まだまだ多くの懸念があります。この対応で全てが完了したわけではありません。これらのケースに対応できるように仕組みをさらにブラッシュアップしたり、定期的に棚卸したりするなどの対応が必要になることでしょう。
しかし、この記事が増加するTODOコメントと向き合い、立ち向かう長い旅の第一歩となることを願っています。
*1:ビジネスデータの価値を最大化することをミッションとし、データの力でSansanを牽引するための部署
