【Googleスプレッドシート】Apps Scriptのコード補完を活用する書き方!型ヒントと関数定義

GoogleスプレッドシートのApps Scriptエディタでは、標準のコード補完は限定的です。しかし、JSDoc形式のコメントで型ヒントを記述することで、引数や戻り値の型を明示し、補完を大幅に向上させることができます。この記事では、関数定義に型ヒントを追加する具体的な書き方と、それによって得られる恩恵を解説します。コード補完を活用して、スクリプト作成の効率を高めましょう。

なぜコード補完が弱いのか? JSDocで解決する仕組み

Apps Scriptのエディタは、JavaScriptの動的型付け言語の特性上、変数や関数の型を推定できません。そのため、補完候補が少なく、誤った引数を渡すバグが発生しやすいです。JSDocはコメント形式で型情報を付与する方法です。エディタが解析し、関数のシグネチャや変数の型を認識できるようになります。これにより、正確なコード補完と警告表示が可能になります。型情報を書く手間はありますが、大規模なスクリプトでは生産性が大幅に向上します。

型ヒントを付けた関数定義の書き方手順

1. 関数の上にJSDocコメントを追加する
   関数定義の直前に、/** で始まるコメントブロックを記述します。この中に @param や @return タグを入れます。コメントは必ず /** */ 形式で書き、各行の先頭に * を付けます。
2. 引数に @param タグで型を指定する
   各引数に対して @param {型} 引数名 説明 の形式で記述します。型には string, number, boolean, Array, Object などが使えます。例えば @param {string} name ユーザー名 と書くと、呼び出し時に name が文字列であることが補完されます。
3. 戻り値に @return タグで型を指定する
   関数の戻り値に @return {型} 説明 を追加します。戻り値がない場合は @return {void} とします。これにより、関数の結果を受け取る変数に型が伝わり、その後のメソッド補完が効くようになります。
4. カスタムオブジェクトには @typedef で型定義を作成する
   複数のプロパティを持つオブジェクトを扱う場合、@typedef を使って独自の型を定義します。例えば @typedef {{name: string, age: number}} Person と定義し、関数のパラメータで @param {Person} p と使うことで、p.name などの補完が有効になります。

具体的な関数例

以下は、JSDocコメントを付けた関数の例です。

/**
 * 指定した範囲のセルの値を合計します。
 * @param {Array<Array<number>>} values 数値の2次元配列
 * @return {number} 合計値
 */
function sumValues(values) {
  let total = 0;
  for (let row of values) {
    for (let cell of row) {
      total += cell;
    }
  }
  return total;
}

このように記述すると、sumValues関数を呼び出す際に、valuesの型が Array<Array<number>> であることが補完されます。また、戻り値が number であることも伝わるため、結果を受け取った変数に対して数値操作の補完が有効になります。

@typedefを使ったカスタム型の定義例

スプレッドシートの行データを表す型を定義します。

/**
 * @typedef {{name: string, score: number, grade: string}} StudentRecord
 */

/**
 * 生徒のリストを取得します。
 * @param {string} sheetName シート名
 * @return {Array<StudentRecord>} 生徒レコードの配列
 */
function getStudents(sheetName) {
  // 実装
}

このようにすることで、getStudentsの戻り値の各要素に対して、name、score、gradeのプロパティが補完されるようになります。

注意点とよくあるミス

JSDocの書式が正しくない場合

JSDocコメントは厳密な書式が求められます。例えば @Param のように大文字で書くと認識されません。また、@param {string} name のように型の前後にスペースを入れないとエラーになります。エディタが正しく解析しているか、補完が効くかどうかを確認しながら記述しましょう。

型ヒントが多すぎて逆に混乱する場合

すべての変数に型を付ける必要はありません。頻繁に使用する関数や、複雑なオブジェクトに絞って記述すると効率的です。あまりに細かく定義するとメンテナンスが負担になるため、バランスが大切です。

サードパーティのライブラリでは型定義が利用できない場合

Apps Scriptの標準サービスクラス(SpreadsheetAppなど)は、もともと型定義が用意されていますが、外部ライブラリでは型情報がない場合があります。その場合は、自分で型定義を追加するか、@typedef を使って補完を補うことができます。

主要なJSDocタグの種類と用途

まとめ

この記事では、Apps ScriptにおけるJSDocコメントを使った型ヒントの記述方法と、それによるコード補完の向上について解説しました。@paramや@returnを適切に記述することで、関数の使い方が明確になり、補完が効率化されます。また、@typedefを使えば複雑なオブジェクトも補完対象にできます。これらのテクニックを活用して、スクリプト開発の生産性を向上させてください。まずは普段使っている関数にJSDocを追加してみることから始めましょう。