こんにちは、etau です 🤓
ちょっと面倒だけど、あるととても便利なドキュメンテーション コメントは、弊社のコーディング ガイドラインでは、必ず書くことになっています。
どんなに短い関数、どんなに小さいクラスやメソッドでも省略不可です。
メンテナンスや機能追加する場合にも、ドキュメンテーション コメントをサラッと読んで、必要に応じてコードを読み込んでいくほうが省力化できます。
ドキュメンテーション コメントとは
ドキュメンテーション コメントは /** ではじまり */ でおわる、おもに関数についての説明です。
簡単な説明であれば 1 行で書くことも可能です。
/** myFunction に関する説明です */
function myFunction() {
}
通常は、以下のように書くことになります。
/**
* myFunction に関する説明です
* @param {number} num - 仮引数の説明です
* @return {boolean} 戻り値の説明です
*/
function myFunction(num) {
return num === 0;
}
今回の記事では触れませんが GAS 特有のカスタム関数用の @customfunction というものもあります
GAS に関するドキュメンテーション コメントを書こうとすると、ウェブサイト上にあまり情報がないため、どのように書けばよいのか戸惑われる方が多いと思います。
そこで、弊社で参考にしているサイトをご紹介いたします。
ドキュメンテーション コメントを書く場合の参考ウェブサイト
Google Apps Script (GAS) は JavaScript ベースのプログラミング言語ですので、JavaScript のドキュメンテーション コメントについて書かれているウェブサイト JSDoc をベースとしています。
つづいて Google JavaScript Style Guide です。
弊社では、この 2 つをもとにドキュメンテーション コメントとコーディング ガイドラインを設定しています。
この面倒なドキュメンテーション コメントを書くと、どのようなよいことがあるのでしょうか。
ドキュメンテーション コメントのメリット
以下の関数に書かれたドキュメンテーション コメントを例にあげて説明します。
/**
* 数値を倍にする関数
* @param {number} num - 倍にする数値
* @return {number} 倍にした数値
*/
function double(num) {
const doubleNumber = num * 2;
return doubleNumber;
}
ドキュメンテーション コメントには、関数がどのような処理をするのか、仮引数の情報 (数・型・説明)、戻り値の情報 (型・説明)が明記されています。
今回、例に上げた double 関数のキュメンテーション コメントでは、関数が数値を倍にすること、倍にしたい数値型の仮引数を受けて、倍にした数値型の戻り値を返すことが確認できます。
また、別の myFunction 関数から、この double 関数を呼び出すと、ドキュメンテーション コメントに書かれた内容にしたがって、ポップアップが表示される点もメリットとしてあげられます。
小さなプログラムで関数をわけずに書く場合であれば、ドキュメンテーション コメントの必要性は低いですが、以下のような場合にコードの可読性や可搬性があがります。
- 関数を処理単位で細かくわけて書く
- 大きなプログラムで gs ファイルがいくつにも別れて書かれている
- 別のプロジェクトから関数やクラス単位でプログラムを移植する
つまり、動くことを目的としたコードを書いていた時期からステップ アップして、開発やメンテナンスを楽におこなうことを目的としたコードを書く場合に、本領を発揮するのがドキュメンテーション コメントというわけです。
それでは、さきほどのドキュメンテーション コメントとポップアップされた内容を比較していきます。
ドキュメンテーション コメントとポップアップとの比較
関数の説明
ドキュメンテーション コメントのトップに書かれている関数の説明はここに表示されます。
仮引数名
@param からはじまるものが仮引数の情報です。
} の後ろに仮引数名を書くことで、ポップアップにも表示されます。
仮引数の型
仮引数の型は {} 内に明記します。
仮引数の説明
ドキュメンテーション コメント側の - を省略すると、ポップアップの・ は表記されなくなります
戻り値の型
@return から始まるものが戻り値のドキュメンテーション コメントです。
JsDoc では@returns と表記されており、どちらでも問題なく利用できます。
戻り値のない関数の場合 void と表示されます
利用頻度の高い型については、以下で説明します。
型の表記
はじめに注意点ですが、この型表記をおこなうことによって、型を強制するわけではありません。
ですが前述のとおり、関数を作る側と関数を使う側との認識を共有できるメリットがあります。
数値型
{number}
文字列型
{string}
真偽値型
{boolean}
配列
{Array.<'配列内の値の型'>}
{Array.<number>} 数値型を値として持つ配列の例
{Array.<Array.<'配列内の値の型'>>} 2 次元配列の場合
{Array.<Array.<string>>} 2 次元配列で文字列型を値として持つ配列の例
‘配列内の値の型’ の部分は省略することもできます
オブジェクト
{Object.<'オブジェクトの値の型'>}
{Object.<string>} 文字列型を値として持つオブジェクトの例
日付型
{Date}
独自クラスの型
{'独自クラス名'}
{Datetime} Datetime クラスから生成されたオブジェクトの例
よく使うのは、このあたりです。
Google Workspace services で利用されるオブジェクトの型についても、簡単に説明していきます。
GWS で利用されるオブジェクトの型表記はトップ レベル オブジェクトと、そこから呼び出されるクラスをドットでつないで表記します。
例としてスプレッドシートの Sheet オブジェクトと Range オブジェクトの 2 つの型表記の方法を説明します。
スプレッドシートの Sheet オブジェクト
{SpreadsheetApp.Sheet}
スプレッドシートの Range オブジェクト
{SpreadsheetApp.Range}
型 = オブジェクト (トップ レベル オブジェクト.クラス名) と覚えておくと理解しやすいですね。
また、スプレッドシート内の値を操作する場合などは、複数の型が混在します。
そのような場合は、以下のように表記できます。
複数の型の表記
複数の型を想定している場合は、| (パイプライン) を利用して、併記することが可能です。
{number|string}
上記は「数値型と文字列型のいずれかである」ということを表しています。
きっと Date オブジェクトの場合は {number|...number|string|Date} なんて書かれているのではないでしょうか
おまけ
また、変数や定数についても 1 行でコメントを書く方法があります。
/** @type {string} */
const hoge = 'hoge';
このように書けば、各型についてのメソッドが変数・定数を利用する場合に候補に上がってきます。
実際の定数に代入された値よりも、コメントを優先してコンテンツ アシストを表示させます。
面白いですね。
まとめ
規模感の大きなプログラムには必須と言っていいであろうドキュメンテーション コメントの紹介でした。
この記事を読んだみなさんに書かないと言った選択肢はないですよね。
コメントについて、大好きな本の中に、大好きな一文があるので紹介します。
ポチップ
ドキュメンテーション コメント以外のコメントをつける場合、「変数名や関数名で補えないのか」「理解しやすいコードにリファクタリングすることでコメントしなくていいのではないか」「関数のサイズが適切なのか」など、いろいろと考える必要があります。
それに比べて、ドキュメンテーション コメントは書くことが前提です。
もちろん、意味のないコメントでもありませんし、価値のないコメントでもありません。
未来の自分やチームのために、しっかりと書き記していきましょう。
今後もアップデートしていきます
