外資系企業でソフトウェアエンジニアをしております、タロイモと言います。今日もよろしくお願いします。

開発現場では、コードは自分だけが読めるものではいけません。
そのため、コメント(メモ)として関数やクラスの詳細を書かなければいけません。

しかし、そのコメントが統一されたもので（ルールが）ないと、プログラマーは何を書けば良いかわからないし、読む方も読みづらいです。

会社や組織、チーム独自にコメントのルールがある場合もありますが、その生成を楽にしてくれるツールもあります。

それがDocです。

今回は、そのDoc機能を紹介します。
今回はJS DocというJavaScript用のDocで例を紹介しますが、RubyにはRDoc、JavaにはJavaDocなど各言語であります。

1. JSDocの使い方

JSDocは、エディターを使うとかなり開発効率が上がると思います。
JSDocに対応しているエディターVSCodeで、以下のように関数を作りJSDocをコメントとして書くと、

そして、以下のように別のファイルで関数にカーソルを合わせたときに、JSDocコメントが表示されます。

完璧な記述をする必要はありませんが、できるだけ推奨されている書き方で記述すると良いそうです。

HTMLでも出力することができます。
npmでjsdocをインストールして、

＄　npm install -g jsdoc

以下のファイルbook.jsに

$ jsdoc book.js

以上のコマンドを入力すると、

このようにHTMLが生成されます。
これをブラウザで開くと、

関数の詳細が表示されます。

エディターがお勧めですが、HTMLでも出せるので両方のやり方を覚えておくと良いでしょう。

2. JSDocの書き方

"/**"で初めて、"*/"で終わります。
その間に記述がある分だけ"*"を書きましょう。

/**
* [記述]
*/

変数
@typeの後の{}内に変数の型（String, Number, Boolean）を書き、そのあとに変数の説明を書きます。

/**
* @type {Number} 年齢
*/
let age = 23;

配列
@typeの後の{}内にArrayと書き、そのあとに配列の説明を書きます。

/**
* @type {Array} 年齢の配列
*/
let ageArray = [10, 22, 30];

連想配列
最初に@typeで連想配列の説明を書きます。連想配列はオブジェクトの扱いなので、{}の中はobjectと書きます。
次に連想配列のオブジェクト内の@typeで連想配列のペアが何を意味しているのかを書きます。{}内は連想配列の値（value）の型を書きます。

/**
* @type {Object} 会員情報の連想配列です
*/
const memberInfo = {
 /**
  * @type {Number} 会員番号
  */
 "id": 1,
 /**
  * @type {String} 会員名
  */
 "name": "taro imo"
}

クラス（インスタンス）
はじめにクラス（インスタンス）の説明をします。
@constructorがコンストラクタであることを表します。（なくても良い）
@thisが何を指しているのか{}の中に書きます。
@paramで関数の引数の説明を書きます。{}の中には関数の引数の型を書きます。

/**
* Personクラスのインスタンスを作成する。
* @constructor
* @this {Person}
* @param {String} name 名前
* @param {Number} age 年齢
*/
let Person = function(name, age) {
   this.name = name;
   this.age  = age;
   }

let taroImo = new Person('taroImo', 23);
console.log(taroImo.name); // taroImo
console.log(taroImo.age); // 23

関数
まずコメントの最初に関数の説明を書きます。
次に@paramで関数の引数の説明を書きます。{}の中には関数の引数の型を書きます。
最後に@returnで返り値の説明を書きます。{}の中には返り値の型を書きます。
*関数内の変数のJSDocは省いています。

/**
* 10年後の年齢を返す
* @param {Number} age 年齢
* @return {Number} 10年後の年齢
*/
function tenYearsLater(age){
 let tenYearsLater = age + 10;
 return tenYearsLater;
}

3. まとめ

今回は複数人での開発効率をあげるDocについて紹介してみました。

Docを利用することで時間短縮をし、快適な開発を実現してみてください。

本日もご精読ありがとうございました。