😊

VSCodeでJSDocを使ってコメントを書こう

2022/07/08に公開

まずはコメントなしでJavaScriptのメソッドを書きます

function test(a, b, c) {
    if (a === b) {
        alert(c);
    }
}

ご覧のように、コメントなしでコードを読むことが難しいです
そこで、JSDocを導入してコメントを書きましょう

JSDocってなに

JSDocは、JavaScriptのコメントの書き方に対するルールです
そして、VSCodeとの相性が非常に良く、プラグインなしでショートカットで簡単に書くことができます

使用の流れは以下のようです

  1. まずはメソッドの上に、/**を打ちます
  2. そこで、autocompleteが自動に表示しますので、Enterを打って改行させます
  3. そうすると、パラメータが自動的に認識され、コメントが生成されました

そして、書き方の以下です
一つ目の*はメソッドのタイトルで、@paramの末端にパラメータの意味や用途などを書きます

/**
 * メソッドのタイトル
 * @param {*} a パラメータの紹介
 * @param {*} b パラメータの紹介
 * @param {*} c パラメータの紹介
 */
function test(a, b, c) {
    if (a === b) {
        alert(c);
    }
}

上の例を例えるなら、このような書き方となります

/**
 * 二つの値を比較し、もし等しいなら何かをポップアップします
 * @param {*} a 比較値①
 * @param {*} b 比較値②
 * @param {*} c ポップアップのテキスト
 */
function test(a, b, c) {
    if (a === b) {
        alert(c);
    }
}

このような書き方によって、メソッドのautocompleteが出てきて、非常にわかりやすくなります

Discussion