【Javascript】 コメントとJsDoc – プログラミング入門

一言でコメントと言っても、単なるコメント文だけでなく、特定の書式もあります。

ここでは、普通のコメントの書き方と、jsDocに従った特に頻繁に利用するコメントを紹介します。

1行コメント

Javascriptでの1行コメントは//を使います。

let price = 100; // 税抜額

// 税込みを計算
price *= 1.1;

//の後は、その行はすべてコメントになります。コメントは実行されないので、自由に書くことができます。

プログラムを読みやすくするため、適度にコメントを書くと非常に良いです。他人が読みやすくするのにも、自分が読み返すためにも書いておきましょう!

複数行コメント

/*と*/で囲みます。

/*
console.logを分解すると, 
consoleは色々な機能を持っていて,
logはそのconsoleの機能の1つ
*/
console.log(10);

/* 1行に収めてもok */

ここで、各行の頭に*とスペースをつけることがしばしばあります。

/**
 * 1行目
 * 2行目
 */

JsDoc

関数のコメント

関数には、引数や戻り値などを、特定のワードを入れた上で書きます。

/**
 * BMIを計算
 * 
 * @param {Number} height 身長(m)
 * @param {Number} weight 体重(kg)
 * 
 * @return {Number} bmiの値
 */
function calcBmi(height, weight) {
    // ...
}

コメントの各行に@...という形で書かれていますね。このように書くことで、エディタ上でこのように表示することができます。

つまり、エディタがそれぞれどのような意味を持つのかを解釈していることになります。

こうすることで、とくにlinterと組み合わせ、引数に入れている値の型が間違っている、戻り値が1個なのに複数ある前提の書き方になっているなどの問題を検出できるようになります。

しばしば利用されるものを紹介します。

• @param {型} 引数名 説明
  • 引数について説明します
  • 型は省略できます. @param hoge
  • 複数の型が入る可能性がある場合、|で区切ります。
    • { Number | Boolean }、{ String | null }
• @return {型} 説明 or @returns {型} 説明
  • @return {Number} BMIの値のように、戻り値について説明します
  • 型は省略できます
• @throws 説明 or @exception 説明
  • 例外を排出する場合があることを示します
• @deprecated
  • 今後使わないでほしい関数やクラスなどにつけます

よく使うのは、StringとNumberです。配列はNumber[]やArray<Number>のように書きます。

変数のコメント

あまり書きませんが、チームに酔ってはメンバ変数に書くなどあると思います。

/**
 * @type {number}
 */
const hoge = 10;

まとめ

プログラムを他人に理解してもらうのももちろんですが、自分が読み返す際にも非常に重要です。

関数のコメントなどでは、JsDocの書き方に従って記述すると、エディタがうまく解釈してくれ、人にとっても見やすいものになります。