TODOコメントを撲滅する仕組みを提供するreminder-lintをOSSで公開しました

こんにちは、FANBASEの中川(@kqito_n)です。

突然ですが、みなさんのGitリポジトリに実施されていないTODOコメントやFIXMEコメントはありませんか？

開発を進めていく中で、以下のようなコメントを書いた経験は誰にでもあるのではないでしょうか。

// TODO: APIの仕様変更後にこの処理を削除する
// FIXME: パフォーマンス改善が必要

これらのコメントはコードの中に埋もれ、開発チームから忘却される事もあるかと思います。

その上、これらが残り続けると、複雑性や認知負荷の増加、延いては最終的に技術的負債として蓄積される側面が危惧されます。

reminder-lintとは

このような課題を解決するべく reminder-lint という検査ツールを開発し、多くの社内部署で利用していたものを、今回OSSとして公開しました。

https://github.com/CyberAgent/reminder-lint

reminder-lint は、コード内のリマインドコメントを自動で検出し、指定された期限を超過した場合にそれらを検査するCLIツールです。プログラミング言語や設定ファイルの種類を問わず、あらゆるファイルに対して動作したり、CI/CDパイプラインに組み込んで継続的にチェックしたりすることができます。

そのほかにも、日付フォーマットのカスタマイズや、リマインドコメントのバリデーション機能など、便利な機能を備えています。

以前、以下の記事で reminder-lint を社内ツールとして紹介しましたが、今回、OSSでの公開に伴い、多くの方がこのツールを活用できるようになりました。

その反響もあって、嬉しいことに社内メンバーから aqua に対応するコントリビュートを頂けたりしています。

使い方

インストール

reminder-lint は以下の方法でインストールできます

Homebrew

$ brew install CyberAgent/tap/reminder-lint

Docker

$ docker run --rm -v "$(pwd):/workspace" --workdir /workspace ghcr.io/cyberagent/reminder-lint:latest run

aqua

$ aqua g -i CyberAgent/reminder-lint

もしくは直接バイナリをダウンロードして使用することも可能です。

基本的な使用方法

reminder-lint の基本的な使用方法について解説いたします。

まず最初に、設定ファイルの生成のためにreminder-lint initコマンドを実行します。これはremind.yml設定ファイルを作成し、チームの開発スタイルに合わせてリマインドコメントの運用をカスタマイズできるようにするためです。

$ reminder-lint init

┌   Initialize reminder-lint
│
◇  Please enter the comment regex
│  remind:\\\\W?
│
◇  Please select the datetime format
│  %Y/%m/%d
│
◇  Please enter the search directory
│  .
│
◇  Remind if no datetime in comment?
│  No
│
◇  Create .remindignore ?
│  Yes
│
Successfully create ./remind.yml
Successfully create ./.remindignore

生成された `remind.yml` 設定ファイルの例を以下に示します。

comment_regex: remind:\\W?
datetime_format: '%Y/%m/%d'
search_directory: .
remind_if_no_date: false
validates:
  datetime:
    format: '%Y/%m/%d

リマインドコメントの表示

以下のコマンドによって設定ファイルに応じたリマインドコメントを出力することができます

$ reminder-lint run # 期限切れのリマインドコメントを検出
$ reminder-lint list # すべてのリマインドコメントを一覧表示

尚、remind.ymlの remind_if_no_date オプションを true に設定すると、日付が指定されていないリマインドコメントも検出することが可能になります

リマインドコメントのバリデーション

チーム開発などでは、リマインドコメントに期限日だけではなく他のコンテキストを明示したいニーズがあるかと思います。

これらはreminder-lint validateコマンドを使用することで、リマインドコメントのフォーマットが正しいかを検証することができます。

例えば期日と担当者を明示したい場合であれば、以下のようにremind.ymlにバリデーションルールを追加します

comment_regex: remind:.*
search_directory: .
trigger:
  datetime: "%Y/%m/%d"
validate:
  datetime:
    format: "%Y/%m/%d"
  assignee:
    format: "@(kqito|arabian9ts|dora1998)"

この状態で$reminder-lint validateコマンドを実行すると、期日と担当者が指定されていないリマインドコメントがエラーとして検出されます。

$ reminder-lint validate

./main.go:11 // remind: hoge: missing date and assignee
Missing `assignee` format: @(kqito|arabian9ts|dora1998)
Missing `datetime` format: %Y/%m/%d

./main.go:14 // remind: 2024/05/02: missing assignee
Missing `assignee` format: @(kqito|arabian9ts|dora1998)

./main.go:17 // remind: @arabian9ts missing date
Missing `datetime` format: %Y/%m/%d

CI/CDとの統合

reminder-lint をCI/CDパイプラインにも組み込むことで、継続的にリマインドコメントのチェックを行うことができます。

name: reminder-lint

on:
  schedule:
    - cron: '0 1 * * 1,2,3,4,5'

jobs:
  run:
    runs-on: ubuntu-latest
    name: reminder-lint
    steps:
      - name: Checkout
        uses: actions/checkout@v5

      - name: Run
        uses: CyberAgent/reminder-lint@latest # Recommended to specify with a full-length commit SHA
        with:
          args: run

まとめ

私が担当している社内の複数プロジェクトで reminder-lint を導入しています。その結果、すべてのTODOコメントやFIXMEコメントに担当者と期限を明示した上で、放置されることなく開発を続けることができています

また、本記事で説明は省略している部分になりますが、期限が切れたリマインドコメントがあった場合にはSlackに通知を送るCI/CDのワークフローの導入を社内プロジェクトで行っており、認知しやすい仕組み化も行っています。

導入後の感想としては、reminder-lint が「放置されたTODOコメントやFIXMEコメントがない状態を保つ文化形成」を手引きするツールとして実際にワークしていると感じています。

本OSSはあくまでも開発環境におけるツールであるため、実際のランタイムには影響を与えません。コードの品質向上に寄与するツールとして、ぜひ気軽にプロジェクトに導入していただければ幸いです

https://github.com/CyberAgent/reminder-lint

みなさまのGitリポジトリに潜むTODOコメントやFIXMEコメントの撲滅に reminder-lint が役立つことを願っています！

タップルのAndroidアプリ開発に1ヶ月参加して学んだこと