【VBAリファレンス】プロが教えるGoogle Apps Scriptの保守性を劇的向上させるコメント術

スポンサーリンク

概要：なぜGASに「コメント」が必要なのか

Google Apps Script（GAS）は、ブラウザだけで完結する手軽さと、Google Workspaceとの強力な連携能力から、業務効率化の要として急速に普及しています。しかし、開発スピードが速い分、コードの「使い捨て」が発生しやすいのも事実です。数ヶ月後の自分や、引き継いだ同僚がコードを見たとき、「これは何のために書いたのか？」「この変数は何を指しているのか？」と頭を抱えることはありませんか。

プロフェッショナルなエンジニアにとって、コードは「コンピュータへの指示書」であると同時に、「他者（未来の自分を含む）への手紙」です。GAS開発においてコメントを適切に記述することは、単なるマナーではなく、長期的な保守運用コストを削減するための戦略的投資です。本稿では、GAS開発におけるコメントの書き方を、実務レベルの視点から徹底的に解説します。

詳細解説：コメントの基本原則とJSDocの活用

コメントには大きく分けて「コードの動作を説明するもの」と「コードの意味を定義するもの」の2種類があります。GASで推奨されるのは、後者を強化する「JSDoc」形式のコメントです。

1. 単一行コメントとブロックコメントの使い分け

基本的な記述方法はJavaScriptに準拠します。
// は単一行コメントで、主に「なぜその処理が必要なのか」という意図を補足するのに適しています。
/* … */ はブロックコメントで、複数行にわたる複雑なロジックの説明や、一時的なコードの無効化（デバッグ時）に使用します。

2. JSDocによる型定義の魔法

GASの最大の特徴の一つは、Googleの各サービス（SpreadsheetApp, DriveAppなど）を扱うAPIが非常に豊富なことです。JSDocを使用すると、エディタ（GAS IDE）上で補完機能が効くようになり、関数の引数や戻り値の型が明確になります。

例えば、カスタム関数を作成する際、以下のように記述します。

/**
 * 指定したスプレッドシートの最終行を取得する
 * @param {GoogleAppsScript.Spreadsheet.Sheet} sheet - 対象のシートオブジェクト
 * @return {number} 最終行の行番号
 */
function getLastRow(sheet) {
  return sheet.getLastRow();
}

このように記述することで、コード補完が正確に働くようになり、タイプミスによるバグを未然に防ぐことができます。

サンプルコード：保守性の高い記述例

以下に、実務で頻出する「メール送信処理」を例に、良いコメントと悪いコメントの対比を示します。

/**
 * フォーム回答者に対して自動返信メールを送信する
 * @param {string} email - 送信先メールアドレス
 * @param {string} userName - ユーザー名
 */
function sendAutoReply(email, userName) {
  // 1. メールの件名を設定（変更の可能性があるため定数化）
  const SUBJECT = "お問い合わせありがとうございます";
  
  // 2. 本文の作成
  const body = `こんにちは、${userName}様。\nお問い合わせを受け付けました。`;

  // 3. Gmailサービスを使用して送信
  // エラーハンドリングが必要なため、try-catchで囲む
  try {
    GmailApp.sendEmail(email, SUBJECT, body);
  } catch (e) {
    Logger.log("メール送信失敗: " + e.toString());
    throw new Error("送信処理で予期せぬエラーが発生しました");
  }
}

このコードでは、処理の内容（1, 2, 3）が簡潔に記述されており、特に「なぜtry-catchを入れているのか」という意図がコメントによって明確化されています。

実務アドバイス：コメントを書く際の「黄金律」

実務の現場で、私が後輩に伝えている「コメントを書く際の鉄則」をいくつか紹介します。

1. 「何をしているか」ではなく「なぜそうしているか」を書く
コード自体を見れば「スプレッドシートから値を取得している」ことは分かります。しかし、「なぜこの列をわざわざ取得しているのか」「なぜこのタイミングでキャッシュをクリアしているのか」という背景はコードからは読み取れません。コメントは「コードの裏側にある背景」を記述する場所です。

2. 「腐ったコメント」を避ける
コードを修正したのにコメントを更新し忘れるケースです。これは非常に危険です。最新のコードと矛盾するコメントは、読み手を混乱させる最大の要因となります。修正時は、必ずコメントもセットでメンテナンスしてください。

3. コメントに頼りすぎない
コード自体を読みやすくする「リーダブルコード」の意識が先決です。関数名や変数名を工夫し、極力コメントがなくても処理の流れが理解できる名前（セルフドキュメンティング・コード）を目指しましょう。コメントはあくまで「最後の補助」です。

4. TODOコメントを戦略的に使う
「現在は仮実装だが、後で修正が必要」という箇所には必ず // TODO: と記述しましょう。GAS IDEでは、タスクリストとして確認できることもありますし、何より後から検索する際に非常に便利です。

まとめ：コメントは開発者への「おもてなし」

Google Apps Scriptは、個人利用から企業のDXツールまで、その用途は多岐にわたります。開発したコードが長期間安定して稼働するためには、技術力だけでなく、読み手への配慮が不可欠です。

プロフェッショナルなエンジニアが書くコードには、必ず丁寧なコメントが添えられています。それは、未来の自分やチームメンバーが、短い時間で正確にコードの内容を理解し、安全に修正を加えるための「おもてなし」なのです。

まずは、明日書くコードの1行から始めてみてください。関数の冒頭にJSDocを書き、複雑な条件分岐の直前に「なぜこの条件が必要なのか」をメモする。それだけで、あなたの書くGASの品質は、一段階上のレベルへと引き上げられます。

GASの世界は、あなた次第でより便利で、よりスマートなものになります。ぜひ、今日から「伝わるコード」を意識した開発を実践してください。あなたの書く素晴らしいスクリプトが、多くの業務を救うことを願っています。

スポンサーリンク
タイトルとURLをコピーしました