概要：なぜGASにコメントが必要なのか
Google Apps Script（GAS）は、ブラウザだけで完結し、外部APIとの連携も容易な強力なツールです。しかし、その手軽さゆえに「とりあえず動くコード」を量産しがちです。数ヶ月後にそのコードを見直したとき、自分自身でさえ「なぜこの処理が必要なのか」と頭を抱えた経験はないでしょうか。Excel VBAの世界で長年培われた「保守性の高いコード」の原則は、GASにおいても例外ではありません。本稿では、GASの特性を最大限に活かしつつ、チーム開発や長期運用に耐えうる「意味のあるコメント」の書き方を解説します。コメントは単なる備忘録ではなく、コードの意図を伝えるための「ドキュメント」であることを理解しましょう。
詳細解説：コメントの役割と記述の黄金律
コメントの目的は「何をしているか（How）」を説明することではありません。それはコード自体が語るべき情報です。真に重要なのは「なぜそうしたのか（Why）」という背景情報です。
1. なぜ（Why）を優先する
コード上の「値の変更」や「複雑な条件分岐」には、必ず理由があります。例えば、特定のAPIの制限を回避するために待機時間を設けている場合、その数値を単に記述するのではなく、APIの仕様や制限内容をコメントに含めるべきです。
2. JSDoc形式の活用
GASはJavaScriptベースであるため、JSDoc（Doc Comments）を積極的に活用しましょう。「/** … */」で囲まれたコメントは、エディタ上で関数にカーソルを合わせた際にポップアップ表示されます。これは、ライブラリとして他のプロジェクトで利用する場合や、チーム開発において絶大な効果を発揮します。引数の型、戻り値、関数の目的を明確に記述することで、自動補完の恩恵を最大化できます。
3. 修正履歴（Change Log）の扱い
かつてはソースコード内に修正日や担当者を記述する習慣がありましたが、現在はGitやGASの「プロジェクトの履歴」機能がその役割を担っています。コード内のコメントに古い修正履歴を残すのは、むしろ可読性を下げるノイズとなります。コメントはあくまで現在のコードの意図を説明するために使いましょう。
サンプルコード：プロ仕様のドキュメント作成
以下は、実務で頻繁に利用される「スプレッドシートからデータを取得し、メールを送信する」という処理を想定した、プロフェッショナルな記述例です。
/**
* 指定されたシートから未送信の案件を抽出し、担当者へ通知メールを送信する。
*
* @param {string} sheetName - 対象となるスプレッドシートのシート名。
* @param {number} limit - 一度に処理する件数の上限（API制限回避のため）。
* @returns {number} 送信が完了した件数。
* @throws {Error} シートが存在しない場合、またはメール送信に失敗した場合。
*/
function sendNotificationEmails(sheetName, limit = 50) {
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheetByName(sheetName);
if (!sheet) {
throw new Error(`指定されたシート「${sheetName}」が見つかりません。`);
}
// 取得範囲の定義
// 1行目はヘッダーのため、2行目から開始する
const range = sheet.getRange(2, 1, limit, 5);
const data = range.getValues();
data.forEach((row, index) => {
// 処理済みフラグのチェック（列E: インデックス4）
// 既に送信済みの場合はスキップする
if (row[4] === '送信済み') return;
try {
const email = row[1]; // メールアドレス
const subject = '【重要】案件進捗のお知らせ';
const body = `${row[0]}様、進捗の更新がございます。`;
// Google Apps ScriptのMailAppサービスを利用
MailApp.sendEmail(email, subject, body);
// 送信成功後にフラグを更新
sheet.getRange(index + 2, 5).setValue('送信済み');
} catch (e) {
// エラー発生時はログに出力し、処理を中断せずに次へ進む
console.error(`送信エラー: ${row[1]} - ${e.message}`);
}
});
return data.length;
}このコードでは、関数全体の役割をJSDocで定義し、処理の各段階で「なぜこのチェックが必要なのか」「なぜこのAPIを選択したのか」という意図を明確にコメントしています。
実務アドバイス：クリーンコードへのアプローチ
コメントを書く前に、まずは「コード自体をコメントなしで読めるようにする」ことを目指してください。これを「自己説明的なコード（Self-Documenting Code）」と呼びます。
・意味のある変数名・関数名をつける：
「a」「b」といった変数名は避け、「targetEmail」「currentRowIndex」のように、何を表しているか一目でわかる命名を徹底しましょう。
・関数は小さく分割する：
一つの関数が長くなればなるほど、コメントで補足が必要な箇所が増えます。「一つの関数には一つの役割だけを持たせる」という原則を守れば、複雑なコメントは不要になります。
・マジックナンバーを排除する：
コード内の「5」や「100」といった数値は、定数として定義し、その意味を名前で表現しましょう。例えば「const MAX_RETRY_COUNT = 3;」と書けば、その数値が何を意味するかのコメントは不要です。
コメントは「コードだけでは表現できない情報」を補うための補助輪です。補助輪に頼り切りになるのではなく、まずは自転車（コード）そのものの性能を上げることが、プロとしての第一歩です。
まとめ：メンテナンス性の高い資産を構築するために
GASは、Excel VBAと同様に、業務自動化の強力な武器となります。しかし、そのコードが「書いた本人にしか解読できないブラックボックス」になってしまえば、組織にとっては負債でしかありません。
今回解説したコメントの書き方は、一見すると手間がかかるように感じるかもしれません。しかし、半年後の自分、あるいはあなたのコードを引き継ぐ同僚にとって、これらのコメントは「道しるべ」となります。
1. JSDocを活用して関数の役割を明確にする。
2. 「何を」ではなく「なぜ」をコメントに書く。
3. コメントが必要ないほど、命名規則と関数設計を工夫する。
これらの習慣を身につけることで、あなたの書くGASは単なるスクリプトから、信頼性の高い「業務システム」へと昇華します。今日からぜひ、一行のコメントに「未来の自分への配慮」を込めてみてください。プロフェッショナルなエンジニアとしての第一歩は、その小さな記述の積み重ねから始まります。
