Zenn
🍧

TODO highlight使っていますか？

2024/10/13に公開
VS Code 拡張機能
コメント
tech

こんにちは。@timdaikです。
今回はVSCode拡張機能の TODO Hightlight がなかなか便利なので紹介します！

https://marketplace.visualstudio.com/items?itemName=jgclark.vscode-todo-highlight

TODO highlightとは？

まず前提として、コメントの文頭にタグをつけて分かりやすくする方法があります。
よく使われる有名なものとしてTODOコメントがあります。
コメントはもともとテキスト表示だけなので、少しでも特徴を付けるための苦肉の策、みたいな理解です。

👇他にも代表的なものとしては以下のようなものが挙げられます。

  • NOTE
  • FIXME
  • DEBUG
  • HACK

しかし、どこまでいってもシンタックスハイライトされないコメントは依然特徴づけが難しいです...

そこで、あらかじめ決めておいた設定に則ってコメントにスタイルを与えてくれるのが、今回紹介する「TODO Highlight」です。

TODO Highlight v2 - Visual Studio Marketplace

カスタマイズ方法

先ほど書いていたハイライトルールの設定方法についてです。
settings.jsonにて以下のようなプロパティを指定します。

  • "todohighlight.isEnable": boolean
    • : ハイライトするかどうか
  • "todohighlight.isCaseSensitive": boolean
    • : キーワードの大文字小文字を区別するかどうかのオプション。trueがおすすめ
  • "todohighlight.defaultStyle": object
    • : 全てのキーワードに対して共通のスタイルを当てることが出来ます。"cursor": "pointer"や"isWholeLine": trueといった大きいスタイルを当てるのがおススメです
  • "todohighlight.keywords": array
    • : 配列の中にそれぞれTODO, NOTEといった、登録したいキーワードごとのスタイルを設定します
  • "todohighlight.include": array
    • : 配列の中にハイライトを有効化して欲しいファイルを指定する。基本的に"**/*.js"のように感じで、ハイライトして欲しい拡張子を追加していく
  • "todohighlight.exclude": array
    • : 上の逆で除外版。例えば"**/node_modules/**"とか
  • "todohighlight.maxFilesForSearch ": number
    • : 後述するタグの検索機能のときに、検索対象となるファイルのマックス数。デフォルト5120となっており、基本いじる必要なし
  • "todohighlight.toggleURI": boolean
    • : 検索時のファイルパス表示をカスタムしてくれる設定

スタイルを充てるときのプロパティはほぼCSSなので、知っていると楽に設定できると思います。

カスタマイズ例

基本設定と一通りメジャーなプレフィックスのスタイル設定をしてみました。
自分の場合、絵文字があったほうが分かりやすいので、before要素にそれぞれ絵文字を設定しました！

settings.json
{
  // NOTE: TODO Highlight v2の設定
  "todohighlight.isEnable": true,
  "todohighlight.isCaseSensitive": true,
  "todohighlight.defaultStyle": {
    "color": "#222",
    "cursor": "pointer",
    "borderRadius": "4px",
    "isWholeLine": true
  },
  "todohighlight.keywords": [
    {
      "text": "TODO:",
      "before": {
        "contentText": "✅"
      },
      "color": "#222",
      "backgroundColor": "#ffaa00",
      "overviewRulerColor": "#ffaa00"
    },
    {
      "text": "FIXME:",
      "before": {
        "contentText": "🐛"
      },
      "color": "#fff",
      "backgroundColor": "#ff33aa",
      "overviewRulerColor": "#ff33aa"
    },
    {
      "text": "NOTE:",
      "before": {
        "contentText": "📝"
      },
      "color": "#fff",
      "backgroundColor": "#0066ff",
      "overviewRulerColor": "#0066ff"
    },
    {
      "text": "HACK:",
      "before": {
        "contentText": "🧑‍💻"
      },
      "color": "#333",
      "backgroundColor": "#00ff00",
      "overviewRulerColor": "#00ff00"
    },
    {
      "text": "REVIEW:",
      "before": {
        "contentText": "😎"
      },
      "color": "#fff",
      "backgroundColor": "#aa00ff",
      "overviewRulerColor": "#ffab00",
      "cursor": "pointer",
      "border": "1px solid #eee",
      "borderRadius": "4px"
    },
    {
      "text": "DEBUG:",
      "before": {
        "contentText": "🔍"
      },
      "color": "#222",
      "backgroundColor": "#ddeeff",
      "overviewRulerColor": "#ddeeff",
      "cursor": "pointer",
      "border": "1px solid #eee",
      "borderRadius": "4px"
    }
  ],
  // "todohighlight.keywordsPattern": "TODO:|FIXME:|NOTE:|HACK:|REVIEW:|DEBUG:",
  "todohighlight.include": [
    "**/*.js",
    "**/*.jsx",
    "**/*.ts",
    "**/*.tsx",
    "**/*.html",
    "**/*.php",
    "**/*.css",
    "**/*.scss",
    "**/*.json"
  ],
  "todohighlight.exclude": [
    "**/node_modules/**",
    "**/bower_components/**",
    "**/dist/**",
    "**/build/**",
    // "**/.vscode/**",
    // "**/.github/**",
    "**/_output/**",
    "**/*.min.*",
    "**/*.map",
    "**/.next/**"
  ],
  "todohighlight.maxFilesForSearch": 5120,
  "todohighlight.toggleURI": false
}

わたしのオススメ設定としては、

  • 絵文字の追加
    • beforeのcontentTextに任意の絵文字を指定する
    • できるだけプレフィックスと親和性のあるやつ、背景色と被りにくいものを選んだほうが良い
  • "isWholeLine": true
    • 指定したパターンだけでなく、行全体に対してスタイルが当たるようになる
    • 👉圧倒的にコメント箇所が目立つ
    • 賛否あると思う

使ってみた

記入例

次のように書くと、

TODO: 今日の夜ご飯を考える

FIXME: XXXをYYYに修正する

NOTE: あとで自作コンポーネントに切り替える（処理の概要とか）

HACK: XXXを使ってYYYを解決した

REVIEW: ここってXXXのほうが良いんじゃない？

DEBUG: （`console.log()`行の右横にコメントに書いたり？）

プレビュー

こう見えます。
コメントハイライトのプレビュー画像
コメントハイライトのプレビュー画像

"isWholeLine": falseを指定した場合も一応載せておきます。
プレフィックスのみにスタイル充てたバージョン
プレフィックスのみにスタイル充てたバージョン

プレフィックスごとの検索も可能

プレフィックスを付けたのは良いけど、どんだけ目立たせてもファイルを閲覧していないと意味がないじゃん！という問題があります。
ということも想定して、この拡張機能にはプレフィックスごとの検索ができるようになっています。
流石ですね。

コマンドラインでプレフィックスの選択
コマンドラインでプレフィックスの選択

検索をするとターミナルの出力タブにて以下のように、ファイルと該当行・コメントがリスト表示されます。

あとがき

今回の記事を書き始めた時の動機は、遡るとインターンになります。
インターン期間中はメンターさんにレビューを沢山していただいたのですが、よくTODOコメントを使うように言われました。

なのでインターン終了後も積極的にコメントにプレフィックスを使っていたのですが、こいつらをもっと見やすくするものはないかと探して見つけたのがこの拡張機能になります。

使い勝手の批評を勝手にさせてもらうと、やはり設定するプレフィックスのパターンを自由に決められるし、スタイルの自由度も高めなので便利ですね。
jsonで設定できるのも個人的には嬉しいポイント。

普段からコメントにプレフィックスを付けている人には是非とも使って欲しい拡張機能でした！
それでは👋

GitHubで編集を提案

Discussion