⚒️
【VScode】コメントを管理しやすくするおすすめの拡張機能と利用方法

2024/12/23に公開
Flutter
VS Code
extension
tech
 はじめにソースコードにコメントを残している時に、以下のようなことを思ったことはありませんでしょうか？
コメントをTagごとに整理したい
特定のコメントだけ一覧で表示したい
特定のコメントに簡単にアクセスしたい
特定のコメントを強調して表示したい
今回はそんな悩みを解決してくれる便利な拡張機能とその使い方をご紹介したいと思います。

 記事の対象者VScodeでコーディングしている方
ソースコードのコメントの取り扱いに悩んでいる方

 記事を執筆時点での筆者の環境[✓] Flutter (Channel stable, 3.24.1, on macOS 15.0.1 24A348 darwin-arm64, locale ja-JP)
[✓] Android toolchain - develop for Android devices (Android SDK version 34.0.0)
[✓] Xcode - develop for iOS and macOS (Xcode 16.0)
[✓] Chrome - develop for the web
[✓] Android Studio (version 2023.3)
[✓] VS Code (version 1.94.0)

 1. 完成系の紹介と使用するサンプル
コメントの種類に応じて独自のTagを設定しています。

Tagに応じてソースコード上で文字色が変わる設定にしています。

VScodeのアクティビティーバー内に表示されている拡張機能のTODOs （スクショの緑枠で囲んだアイコン）を選択すると、特定のコメントをTagごとに整理して一覧で表示することができます。

またその中のコメントを選択すると、該当のコードにジャンプすることができます。

これらを実現するために使用している拡張機能は次の二つです。

 拡張機能１. Better Commentshttps://marketplace.visualstudio.com/items?itemName=aaron-bond.better-comments
BetterCommentsは設定したTagに対してのコメントに色をつけることができます。

こちらも基本設定ですでにTagが用意されていますが、独自に設定することも可能です。

 拡張機能２. Todo Treehttps://marketplace.visualstudio.com/items?itemName=Gruntfuggly.todo-tree
TodoTreeは設定したTagに対して検索をかけて一覧表示する拡張機能です。

基本設定ですでにTagが用意されていますが、独自に設定することも可能です。

 2. 設定方法
 2-1. 拡張機能のインストールそれぞれの拡張機能をVScodeのアクティビティーバーにある拡張機能から検索し、インストールしてください。

 2-2. settings.jsonを開く⌘ + shift + Pでコマンドパレットを開きます。

検索窓にOpen User Settingsと入力してエンターで開いてください。

 2-3. settings.jsonを編集する以下の設定内容を書いて保存します。

私と同じ設定内容であれば以下をコピペしていただければOKです。
Todo TreeとBetter Commentsの設定内容~/Library/Application Support/Code/User/settings.json
    "better-comments.tags": [
        {
            "tag": "INFO:",
            "color": "#3498DB",
            "strikethrough": false,
            "underline": false,
            "backgroundColor": "transparent",
            "bold": false,
            "italic": false
        },
        {
            "tag": "TODO:",
            "color": "#FF8C00",
            "strikethrough": false,
            "underline": false,
            "backgroundColor": "transparent",
            "bold": false,
            "italic": false
        },
        {
            "tag": "HACK:",
            "color": "#D516D5FF",
            "strikethrough": false,
            "underline": false,
            "backgroundColor": "transparent",
            "bold": false,
            "italic": false
        },
        {
            "tag": "FIXME:",
            "color": "#FF2D00",
            "strikethrough": false,
            "underline": false,
            "backgroundColor": "transparent",
            "bold": false,
            "italic": false
        },
    ],
    "todo-tree.general.tags": [
        "INFO:",
        "TODO:",
        "HACK:",
        "FIXME:",
    ],
    "todo-tree.highlights.customHighlight": {
        "INFO:": {
            "icon": "info",
            "foreground": "#3498DB",
            "iconColour": "#3498DB",
        },
        "TODO:": {
            "icon": "check",
            "foreground": "#FF8C00",
            "iconColour": "#FF8C00",
        },

        "HACK:": {
            "icon": "tools",
            "foreground": "#D516D5FF",
            "iconColour": "#D516D5FF",

        },
        "FIXME:": {
            "icon": "flame",
            "foreground": "#FF2D00",
            "iconColour": "#FF2D00",
        },
    },
適用した場合の全体も参考までに載せておきます。
settings.json全体~/Library/Application Support/Code/User/settings.json
{
    "workbench.iconTheme": "material-icon-theme",
    "dart.flutterSdkPath": "/Users/motokawaharuhiko/dev/flutter",
    "security.workspace.trust.untrustedFiles": "open",
    "explorer.fileNesting.enabled": true,
    "cSpell.userWords": [
        "appauth",
        "Colour",
        "cupertino",
        "genhtml",
        "pkill",
        "pubspec",
        "riverpod"
    ],
    "notebook.formatOnSave.enabled": true,
    "editor.defaultFormatter": "Dart-Code.flutter",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
        "source.fixAll": "explicit",
        "source.organizeImports": "explicit"
    },
    "newFile.expandBraces": true,
    "newFile.defaultFileExtension": ".dart",
    "newFile.showPathRelativeTo": "project",
    "newFile.relativeTo": "project",
    "peacock.favoriteColors": [
        {
            "name": "Angular Red",
            "value": "#dd0531"
        },
        {
            "name": "Azure Blue",
            "value": "#007fff"
        },
        {
            "name": "JavaScript Yellow",
            "value": "#f9e64f"
        },
        {
            "name": "Mandalorian Blue",
            "value": "#1857a4"
        },
        {
            "name": "Node Green",
            "value": "#215732"
        },
        {
            "name": "React Blue",
            "value": "#61dafb"
        },
        {
            "name": "Something Different",
            "value": "#832561"
        },
        {
            "name": "Svelte Orange",
            "value": "#ff3d00"
        },
        {
            "name": "Vue Green",
            "value": "#42b883"
        }
    ],
    // ここから=========================================>
    "better-comments.tags": [
        {
            "tag": "INFO:",
            "color": "#3498DB",
            "strikethrough": false,
            "underline": false,
            "backgroundColor": "transparent",
            "bold": false,
            "italic": false
        },
        {
            "tag": "TODO:",
            "color": "#FF8C00",
            "strikethrough": false,
            "underline": false,
            "backgroundColor": "transparent",
            "bold": false,
            "italic": false
        },
        {
            "tag": "HACK:",
            "color": "#D516D5FF",
            "strikethrough": false,
            "underline": false,
            "backgroundColor": "transparent",
            "bold": false,
            "italic": false
        },
        {
            "tag": "FIXME:",
            "color": "#FF2D00",
            "strikethrough": false,
            "underline": false,
            "backgroundColor": "transparent",
            "bold": false,
            "italic": false
        },
    ],
    "todo-tree.general.tags": [
        "INFO:",
        "TODO:",
        "HACK:",
        "FIXME:",
    ],
    "todo-tree.highlights.customHighlight": {
        "INFO:": {
            "icon": "info",
            "foreground": "#3498DB",
            "iconColour": "#3498DB",
        },
        "TODO:": {
            "icon": "check",
            "foreground": "#FF8C00",
            "iconColour": "#FF8C00",
        },

        "HACK:": {
            "icon": "tools",
            "foreground": "#D516D5FF",
            "iconColour": "#D516D5FF",

        },
        "FIXME:": {
            "icon": "flame",
            "foreground": "#FF2D00",
            "iconColour": "#FF2D00",
        },
    },
     // ここまで=========================================>
}
コツとしてはBetter CommentsとTodo Treeで設定するタグ名とカラーを同じにすることで統一感が出て見やすくなります。

 Better Commentsの設定項目の説明"better-comments.tags": [
  {
    // タグ名（例: "FIXME:"）
    "tag": "FIXME:", 
    // タグの文字色を指定する（例: 赤色(#FF2D00)）
    "color": "#FF2D00", 
    // タグの文字に取り消し線をつけるかどうか (true で取り消し線を表示)
    "strikethrough": false,
    // タグの文字に下線をつけるかどうか (true で下線を表示)
    "underline": false,
    // タグの背景色を設定する (例: "transparent"で背景色なし)
    "backgroundColor": "transparent",
    // タグの文字を太字にするかどうか (true で太字)
    "bold": false,
    // タグの文字を斜体にするかどうか (true で斜体)
    "italic": false
  }
]

 Todo Treeの設定項目の説明"todo-tree.general.tags": [
        // ここに設定したいタグを設定
        "INFO:",
        "TODO:",
        "HACK:",
        "FIXME:",
    ],
    // 各タグの見た目(色やアイコン)をカスタマイズする
    "todo-tree.highlights.customHighlight": {
        // TODO: タグの設定
        "TODO:": {
          // 表示アイコンの種類を設定
          "icon": "check",
          // タグに適用するテキストの色
          "foreground": "#FF8C00",
          // アイコンの色
          "iconColour": "#FF8C00"
        },
    },
!基本的に保存すればすぐに反映されますが、もしも反映されない場合はVScodeをリロードすると反映されます。

⌘ + shift + Pでコマンドパレットを開きます。
Reload Windowを入力してエンターを押します。



 3. 使いやすくするための一工夫以下はFlutter特有のものだと思います。

 3-1. タグ名にコロン :をつける
これは主にINFOタグを使う場合です。

INFOだけだとios/Runner.xcodeproj/project.pbxproj内の文言がTodo Treeに引っかかってしまうので、INFO:で登録すると大丈夫になります。

また、基本的なコメントの慣習的にはコロンをつけるので全てのタグにコロンをつけるのがおすすめです。

 3-2. 既存のTODOコメントを削除する
今度はTODO:タグを使う場合です。

以下の三つのファイルですでにTODO：がコメントに記載されています。
linux/flutter/CMakeLists.txt
windows/flutter/CMakeLists.txt
android/app/build.gradle
こちらもTodo Treeに引っかかってしまうので削除しておきます。
!もしもTODOタグを使わなければこの内容はスルーでOKです。

 3-3. リントの設定
Flutterの場合はTODOとHACKキーワードは問題タブで指摘に上がってきます。

私の場合はここら辺は問題で指摘されたくないので、リントルールのエラーの対象から除外しています。

逆にFIXMEタグはプルリクに含めたくない、プルリクに出す前には消すべきコメントとしているので、リントルールの除外には含めていません。

INFOは元から問題には上がってこないので特に設定しなくても大丈夫です。
analysis_options.yaml
analyzer:
    // 省略
  errors:
    # TODOコメントをエラーとして扱わないようにします。
    TODO: ignore    
    # HACKコメントをエラーとして扱わないようにします。
    HACK: ignore
参考までにyamlの全文を載せておきます。
analysis_options.yamlの全文analysis_options.yaml
# very_good_analysisの標準的なリントルールセットを読み込みます。
include: package:very_good_analysis/analysis_options.yaml

analyzer:
  language:
    # ジェネリクスを使用する際に、型パラメータを省略できるようにします。
    strict-raw-types: false

  plugins:
    # custom_lintプラグインを利用して、カスタムリントルールを適用します。
    - custom_lint
    
  exclude:
    # 自動生成ファイル（g.dart）をリントから除外します。
    - lib/**.g.dart
    # 自動生成ファイル（freezed.dart）をリントから除外します。
    - lib/**.freezed.dart
    # firebase関連のコードを含む特定のディレクトリ内のファイルをリントから除外します。
    - lib/core/firebase/**.dart
    # flavor_firebase_options.dartファイルをリントから除外します。
    - lib/core/flavor_firebase_options.dart
    # テスト用のモックファイル（mocks.dart）をリントから除外します。
    - test/**.mocks.dart

  errors:
    # TODOコメントをエラーとして扱わないようにします。
    TODO: ignore    
    # HACKコメントをエラーとして扱わないようにします。
    HACK: ignore
    # switch文でdefaultケースがなくてもエラーとしないようにします。
    no_default_cases: ignore

linter:
  rules:
    # pubspec.yamlの依存関係がアルファベット順にソートされていなくても警告しないようにします。
    sort_pub_dependencies: false
    # パブリックメンバーにドキュメントコメントがなくても警告しないようにします。
    public_member_api_docs: false
    # メソッドやコンストラクタの引数に直接値を割り当てることを禁止しないようにします。
    parameter_assignments: false
    # TODOコメントが特定のスタイルに従っていなくても警告しないようにします。
    flutter_style_todos: false
    # assertにメッセージがなくても警告しないようにします。
    prefer_asserts_with_message: false
    # 使用しているパッケージにpubspec.yamlから参照していないものがあっても警告しないようにします。
    depend_on_referenced_packages: false
    # switch文でdefaultケースがなくても警告しないようにします。
    no_default_cases: false

 3-4. TODO ThreeのTODOsタブを使いこなす
 1. 検索範囲を設定する
確か最初は検索範囲が設定されていなかったはず（うろ覚え）。

なので、ちゃんと書いたのに表示されない人は設定しましょう。

アクティビティモニターの虫眼鏡あたりまたは空白のところで右クリックし、

メニューの中からScan Workspace Onlyを設定しましょう。

 2. 表示切り替えなどのボタンを理解しよう
基本的には画像に色をつけたもので言うと、赤、青、緑のボタンがよく使うと思われます。

おすすめ設定も添えておきます。
赤：表示切り替え

おすすめ=> Show Tags Only View
青：タグごとにまとめるかどうか

おすすめ=> Ungroup by Tag
黄：検索
緑：再読み込み
紫：展開したディレクトリを閉じる

 4. タグの設定基準ここは個人ごとの好みやチームの取り決めがあればそちらが優先される項目です。

一旦私の設定理由をご説明します。
まず、コメントのタグはあまり細かくしすぎると覚えるのが大変ですし、タグをつけるものはより強調したいものだと思います。

いわゆるブックマーク的な使い方がしたいと考えています。

よって必要最低限にしたいのです。ではどういった時にコメントを書き、そのコメントを強調したいかを考えた時、私は以下の理由で決めています。
普通のコメント

変数、関数のドキュメントコメントや関数内の処理の説明など
INFO:

コメントをつけないと誰もこの処理を理解できないであろうもの
TODO:

今回のプルリクでは対応しないけど、次のプルリクで対応するので忘れないようにする
HACK:

動作的には問題ないが後々リファクタリングしたい箇所で、GitHubのissueとセットで書くと尚良い
FIXME:

プルリクやモブプロやペアプロなどで指摘されて治さなければいけないもの、プルリクには含めてはいけないメモ

 終わりに本記事では、Better Comments と Todo Tree を使ってコメントを管理しやすくする方法をご紹介しました。

ちょっとした工夫や設定の統一で、コメントが見やすくなり、実装漏れの確認も効率的になります。
普段からコメントを書いていても、どこに何を書いたか忘れてしまうことは珍しくありません。

しかし、今回ご紹介した拡張機能を使うことで、タグごとにコメントが一覧化され、コードの該当箇所へ素早く移動することが可能です。
また、コメントのタグや色をチームで揃えたり、リントのルールをカスタマイズすることで、コメントによる情報共有がよりスムーズになると思います。
ぜひ、Better Comments と Todo Tree を活用して、コードの可読性とチーム開発の効率を高めてみてください。

最後までお読みいただき、ありがとうございました。