はじめに
JavaScirptの言語仕様外の特有の書き方、アノテーションについてまとめたいと思います。
※一部、strict モードなど言語仕様にあるものもありますが合わせて紹介します。
strict モード
ECMAScript5 で実装された strict モードで動作させます。例えば、変数を宣言せずに代入するといったコードを記載するとエラーが発生するようになります。ES6モジュール形式のJavaScirptを動作させた場合は、自動でstrictモードが有効化されます。
使い方
JavaScriptのソースコードの先頭や、ブロック文の最初で"use strict";と記載する。
"use strict";
グローバル変数
グローバル変数（宣言せずに利用してもエラーを発生させないようにする変数）を設定できます。VSCode、NetBeansなどで利用できます。
使い方
JavaScriptのソースコードの先頭に以下のように、コメントでglobalから続いて、変数宣言を記載します。必ず/*と*/による複数行コメントで括ってください。
/* global WSH, WScript */ // WSH と WScript のグローバル変数が利用可能となる
型推論モード
TypeScriptによる型推論モードを有効化します。VSCodeで利用できます。ただし、2019/8/3時点で拡張子が*.mjsの場合に外部ファイルが型推論機能で正しく読みこめない問題があります。
有効化
JavaScriptのソースコードの先頭に以下のように、コメントで@ts-checkと記載する。必ず、//による1行コメントで記載してください。
// @ts-check // 以降、型推論モードが有効化される。
無効化
型推論機能が有効中に、@ts-ignoreをコメントで書くことで次の行の型推論機能を無効化できます。エラーが出る場合は使用してください。
// @ts-ignore // この行は型推論機能によるエラーチェックが無視される。
型定義
型推論は、JSDocによるコメントを書いたり、型定義ファイル（*.d.ts）を読み込んだりすることで型を設定できます。
型定義ファイルは、設定ファイル（tsconfig.json、jsconfig.json）にファイルの場所を記載したり、明示的にファイルの場所を指定して読み込むこともできます。
明示的な指定方法はJavaScriptのソースコードの先頭に以下のように、コメントでreferenceタグを記載します。必ず、///のように/を3つ繋げて1行コメントで記載してください。
/// <reference path="./hoge.d.ts" />
型定義／ドキュメント用コメント
型推論機能や、JSDoc3、ESDocなどの自動ドキュメント生成用のコメントです。VSCodeの型推論や、ドキュメント作成ツールで利用できます。
使い方
様々な書き方がありますが、基本的に変数や関数のすぐ上に、/**と*/の複数行コメントで囲って定義を行います。コメントの開始は必ず**と2回繰り返して下さい。
2行目以降も最初に*が必要です。最初に解説（複数行可）を記載します。その後は、1行ずつ@から始まる決まった文字列を記載し、そのデータに合わせた文字列を記載していきます。
関数の定義
関数の場合は、以下のようになります。
/**
* ～する関数
* @param {number} x - 引数1
* @param {string} y - 引数2
* @returns {string}
*/
static myfunc(x, y) {
return "test";
}
paramの記載方法
型は次のように書くことが出来ます。
@param {number|string} x - 数値か文字列を引数とする。
@param {Array} x - 配列を引数とする。
@param {?Object} x - オブジェクトを引数とするが、nullを指定してもよい
@param {!Object} x - オブジェクトを引数とする。nullを指定してはいけない
@param {?(number|string)} x - 数値か文字列あるいは、nullを指定しても良い。
@param {number} [x] - 数値を引数とするが、省略してもよい。
@param {number} [x=10] - 数値を引数とするが、省略してもよい。省略した場合はデフォルトを10とする。
@param {{A: number, B: string}} x - AとBをメンバに持つオブジェクトを引数とする。
@param {number[]} x - 数値型の配列。
@param {Object<string, number>} x - キーを文字列、値を数値としたハッシュオブジェクト。
@param {...number} x - 数値型の可変引数
@param {typeof ClassX} x - ClassXの型を引数とする。
@param {function(number, string): boolean} func - 第1引数には数値、第2引数は文字列、戻り値はboolの関数
@param {import("./aaa/bbb.js").MyType} x - 他のファイルに記載してある型情報
変数の定義
変数の場合は、以下のようになります。
/**
* ～する変数
* @types {number}
*/
let x;
型の定義
型宣言のみ記載することも可能です。
/**
* 型のみの情報
* @typedef {Object} MyObject
* @property {number} [x] 省略していい数値
* @property {number} y 省略してはいけない数値
*/
改行方法
解説中に改行する場合は、2回改行で行えます。
/**
* 1行目
*
* 2行目
* @param {number} param1 - 引数1
* @param {string} param2 - 引数2
* @returns {string}
*/
static myfunc(param1, param2) {
return "output1";
};
リスト
リストを使用する場合は、先頭にハイフン-を使用してください。
/**
* ～する関数。
* - ～して下さい。
* - ～に注意。
* @param {number} x - 引数1
* @param {string} y - 引数2
* @returns {string}
*/
static myfunc(param1, param2) {
return "output2";
}
ESLint用アノテーション
VSCodeでESLintを入れることでリアルタイム静的解析を行うことができます。自動で有効化されますが、コメントによって制御が可能です。
アノテーションの例
ファイル単位でルールとエラーレベルを記載する
最初にeslintと記載し、さらにルールとエラーレベルを書きます。/*と*/の複数行コメントで囲います。0は無視、1は警告、2はエラーとなります。
/* eslint no-unused-vars: 0 */ const a = 1;
次の行のみ特定のエラーを無視
次の行のみアノテーションを有効化させるには、eslint-disable-next-lineを使用して、//でコメント化させます。
// eslint-disable-next-line no-unused-vars const a = 1;
おわりに
今回説明したものはどれも、コメントの書き方が///や/**にしないと有効にならなかったり、しっかりそのまま書かないと有効化されないので、注意が必要です。
JavaScriptの純粋なソースコードの書き方も大事ですが、それ以外の記載方法も覚えておくと、色々と役に立つと思います。
以上、おつかれさまでした！
コメント