コーディング時に「アノテーションコメント」を使ってコードを見やすく管理する

アノテーションコメントとは

コードを書いていく上で「適度にコメントを残しておくと、読みやすいコードになる」とよく聞きます。

ただ、コメントの数が多くなってくると「コードの説明をしているコメント」「あとでしたいタスクをメモ書きしているコメント」「なにか理由があって変更してはいけない場所を示している注意書きコメント」などさまざまな種類のコメントが出てきます。

下記のように先頭に「タグ」のような記述を追加しておくと、「そもそもこのコメントは何の目的で残しているのか？」が分かって、把握しやすくなります。

// TODO: あとで引数を追加する

また、あとからファイル検索をしたり拡張機能を使うことで、残タスクの把握もできます。

このように先頭にタグを付けるコメントを「アノテーションコメント（注釈コメント）」と呼びます。

使うタグ名を決めておかないと逆に見にくくなる

たとえば「TODO:」「TODOS:」「TASK:」「CHECK:」のように似たような役割のタグが混在していると、逆に混乱してしまします。

使う数はできる限り少なくして、統一しておかないとあとで検索するときにも不便です。

アノテーションコメントを便利に使うためのVisual Studio Code拡張機能

Visual Studio Codeの拡張機能を使えば、アノテーションコメントをさらに便利に使えます。

Better Comments

Webrandum

Visual Studio Codeでコメントを色分けして管理する「Better Comments」

https://webrandum.net/vscode-plugin-better-comments

Visual Studio Codeでコーディングをしていく中で、未来の自分や他メンバーに向けてコメントを積極的に残しておくと、後でコードを見るときに把握しやすくなります。ただ、「コメント」と言ってもさまざまな目的・用途があります。 単純にコードの説明をしているコメント 重要箇所だから触るときに注意を促す警告用のコメント あとでやるべきタスクを残しているコメント 修正が必要な箇所を残しているコメント今回紹介する「Better Comments」を使えば、コメントの色分けができるので、パッと見で何のコメントなのか分かりやすくなりま...

Better Commentsはアノテーションコメントに装飾を追加できる拡張機能です。

すべて同じ色でもタグのおかげで把握はしやすくなっていますが、色分けされることでさらに把握しやすくなります。

ミニマップにも表示されますし、コードを流し見するときにも目に付きやすくなります。

Todo Tree

Webrandum

Visual Studio CodeでToDoコメントを一覧で表示する拡張機能「Todo Tree」

https://webrandum.net/vscode-plugin-todo-tree

コーディング時に、あとで行うタスクやリファクタリングしたい箇所には「TODO」などを付けてコメントを入れておくと、あとから見たときに把握しやすくなります。今回はそんなタスク用のコメントを一覧表示できる「Todo Tree」についてまとめておきます。Todo TreeTodo Treeはコメントの始めに「TODO」などのタグを付けておくと、一覧で表示して、クリックすると該当箇所まで移動できるVisual Studio Codeの拡張機能です。「あとでやろう」と思ったことをコメントとして残していけば、あとで一覧から探し出せますし、残りのタスク数も確...

Todo Treeはアノテーションコメントの一覧を表示できる拡張機能です。

「TODO:」はあとから行うタスク用のコメントですが、これを一覧で表示させることで残タスクがすぐ把握できます。

アノテーションコメントの色分けもできますが、Better Commentsの方が機能が多いので、色分けは片方に集約した方が管理しやすいです。