皆さんはJavaScriptでのJSDocコメントを利用していますか？ JSDocコメントとは関数や変数の宣言の直前に/** ◯◯ */を書く記法のことです。自由なフォーマットでコメントを書くよりもルールに沿ったコメントを書くことで、プログラムの可読性が高まります。本記事ではJSDocコメントの使い方と導入のメリットを説明してきます。
JSDocコメントの書き方
JSDocコメントは関数や変数の宣言の直前に記載します。先頭のアスタリスクを2つ記載し/** ◯◯ */とし、型情報等を@typeや@paramというキーワードとともに記述します。
/**
* スマートフォンのアクセスであるかを示す真偽値です。
* @type {boolean}
*/
var isSmartphoneAccess = true;
/**
* ページの一番上までスクロールします。
* @param {number} duration スクロール時間のミリ秒です。
*/
function moveTop(duration) {
// anything...
}
この仕組みは他の言語でも存在し、Java言語だとJavadoc、ActionScript 3.0だとASDocが知られています。JavaScriptのコーディング規約「Google JavaScript スタイルガイド – 日本語訳」でも、「全てのファイル、クラス、メソッド、プロパティにJSDocコメントが、適切なタグとデータ型を伴って記されるべきです」と推奨されています。
JSDocコメントのメリット① コードヒント/コード補完の表示
JSDocコメントはコード入力時にツールチップでコードヒントが表示されます。関数のコメントが表示されるため、関数の命令の内容を確認しながら安心してコードを書くことができます。次の動画のようにWebStormでは、プログラムのコードヒントの表示や補完入力の手助けとなっています。
ただし、どのエディターでもJSDocコメントに対応しているわけではありません。各種エディターのJSDocコメントの充実度を表にまとめました。筆者が試したところ、開発環境としてWebStormやVisual Studioが特に優れており、ツールチップにJSDocコメントの情報が全て表示されました。無料のAdobeのBracketsも少しサポートされていて、JSDocコメントの型指定も表示してくれます。対してSublime TextやAtomはサポートが十分ではありませんでした。
※ 上図はクリックで拡大できます
ちなみにAngularJS、CreateJS、ReactなどのメジャーなJSライブラリにおいても、そのソースコードではJSDocコメントが使われています (例 : AngularJS、CreateJS、React)。minifyされる前の(開発者向けの) JSライブラリを使えば、コードヒントとコード補完を表示できます。APIが多岐に渡るJSライブラリを利用するとき、わざわざリファレンスをブラウザで開いたり解説書で調べることなく、コード上で関数の仕様を確認することができます。これはminifyされる前の(開発者向けの) JSライブラリを使うメリットの一つとしてあげられるでしょう。
描画ライブラリCreateJSのAPIを表示したもの
次のページではJSDocコメントを自動的にリファレンスにする方法を紹介します。
