みなさん、こんにちは！
タカハシ(@ntakahashi0505)です。
初心者向けGoogle Apps Script入門、名言Botを作るシリーズをお送りしています。
前回の記事はコチラ。
チャットワークのメッセージ記法を使ってメッセージの装飾をする方法についてお伝えしました。
さて、今回でいよいよこのシリーズも最終回です。
スクリプト自体はいじらないのですが、あとで見返すとき、メンテナンスするときに備えて、ドキュメンテーションコメントを加えていきます。
では、Google Apps Scriptのドキュメンテーションコメントの書き方です。
行ってみましょう！
ドキュメンテーションコメントとは
ドキュメンテーションコメントとは、関数を説明するためのコメントのことです。
関数の宣言の直前に記載する「/**」ではじまり「*/」で終わるコメントで、関数の役割や引数、戻り値などについての情報を記載します。
Google Apps Scriptの公式ドキュメントから拝借して、一例を示すと以下のようなものです。
/**
* 入力数値を2倍にする
*
* @param {number} input - 入力数値
* @return {number} 入力数値を2倍にした数値
* @customfunction
*/
function DOUBLE(input) {
return input * 2;
}
「@」ではじまるタグを指定することで、スプレッドシートのカスタム関数やライブラリとして利用したときに、補完の候補としたり、詳細情報を表示したりすることができます。
カスタム関数やライブラリとして使わなくても、統一してドキュメンテーションコメントを入れておくことで
- 後で見返したり、再利用したりするとき
- 他のメンバーと共同作業するとき
- 関数のメンテナンスをするとき
などに関数の役割をすぐに把握することができますので、ぜひ全ての関数に記入するようにしてくださいね。
使用できるタグとデータ型について
GASのドキュメンテーションコメントの書き方は、JavaScriptで一般的に用いられている書式であるJSDocがベースになっています。
しかし、GASの場合、使用できるタグは、以下の3つのみに限られています。
| タグ | 説明 |
|---|---|
| @param | 引数の {データ型} 仮引数名 – 説明 |
| @return | 戻り値の {データ型} 説明 |
| @customfunction | スプレッドシートのカスタム関数として使う（スプレッドシートのコンテナバインドのときのみ |
型の指定については、主要なものは以下の通りです。
- 数値：{number}
- 文字列：{string}
- 真偽値：{boolean}
- オブジェクト：{Object}
- オブジェクトの配列：{Object[]}
名言Botスクリプトのドキュメンテーションコメント
前回までに作成した名言Botのスクリプトにドキュメンテーションコメントを付与すると以下のようになります。
/**
* スプレッドシートの名言を一つチャットワークに送信するBot
*/
function myFunction() {
const sheet = SpreadsheetApp.getActiveSheet();
const lastRow = sheet.getLastRow();
const token = PropertiesService.getScriptProperties().getProperty('CW_TOKEN');
for(let i = 2; i <= lastRow; i++) {
if(!sheet.getRange(i, 4).getValue()){
const values = sheet.getRange(i, 1, 1, 3).getValues();
let body = '[info]'
body += values[0][0] + '[hr]'; //meigen
body += values[0][1] + '\n'; //person
body += '(' + values[0][2] + ')[/info]'; //info
sendMessage(token, body);
sheet.getRange(i, 4).setValue(true);
if(i >= lastRow) {
sheet.getRange(2, 4, lastRow - 1).clearContent();
}
break;
}
}
}
/**
* チャットワークのマイチャットにメッセージを送信する
*
* @param {string} token - チャットワークAPIトークン
* @param {string} body - マイチャットに送信するメッセージ本文
*/
function sendMessage(token, body){
const cw = ChatWorkClient.factory({token: token});
cw.sendMessageToMyChat(body);
}
これくらいの規模であればコメントなんかイラン！って思われるかも知れませんが、ドキュメンテーションコメントをパッと見るだけで
- スプレッドシートを使う
- チャットワークを使う
- Botなのでトリガーが設置されているかも
などといった情報を仕入れることができます。
急がば回れ、ここは手を抜かずに全ての関数にドキュメンテーションコメントを入れておいたほうが良いでしょう。
まとめ
以上、Google Apps Scriptのドキュメンテーションコメントの書き方についてお伝えしました。
繰り返しになりますが、この小さな手間が後々大きく跳ね返ってきますので、面倒くさがらずに書いてくださいね。
さて、これにてGASによる名言Botの作成シリーズについては完了です。
GASでできることは、コレ以外にも本当に幅広く、その可能性は無限といっても良いほどです。
ぜひ、色々なアイデアを考案して実現してみてくださいね！
連載目次：超初心者向けGASでBotを作りながら基礎を学ぶ
Google Apps Script（GAS）をはじめるためのメリットは山程ありますが、何を作ったらいいの？と悩んでしまうこともありますよね。そんな時に、おすすめしたいのが「Bot」の作成です。このシリーズでは、超初心者向けにGASでBotを作る方法を題材としながら、GASプログラミングの一通りの流れと書き方について学んでいきます。- 【初心者向けGAS】本当の最初の一歩！スクリプトエディタでプロジェクトを開く
- 【初心者向けGAS】はじめてのスクリプトを作成し、保存し、実行する
- 【初心者向けGAS】プログラミングに必須の変数＆定数の使い方とデータ型について
- 【初心者向けGAS】ログを表示するconsole.logの使い方とテンプレート文字列
- 【初心者向けGAS】スクリプト実行時の「承認」でびっくりしないために
- 【初心者向けGAS】Spreadsheetサービスの「オブジェクト」の基礎の基礎を知ろう
- 【初心者向けGAS】スプレッドシートのシートを取得する２つの方法
- 【初心者向けGAS】スプレッドシートのセル・セル範囲とその値を取得する方法
- 【初心者向けGAS】for文を使ったスプレッドシートの繰り返しの超基本
- 【初心者向けGAS】条件分岐をするif文の使い方の超基本
- 【初心者向けGAS】スプレッドシートのセルに値を入力する基礎の基礎
- 【初心者向けGAS】条件に応じてループを制御する2つの方法～break文とwhile文～
- 【初心者向けGAS】スプレッドシートのセル範囲を行数・列数を使って取得する
- 【初心者向けGAS】スプレッドシートのセル範囲をクリアするいくつかの方法
- 【初心者向けGAS】Google Apps ScriptでWeb APIを活用するための基礎知識
- 【初心者向けGAS】面倒なことはライブラリに任せよう！その概要と追加の方法
- 【初心者向けGAS】Chatworkのマイチャットにメッセージを送る最も簡単な例
- 【初心者向けGAS】Google Apps Scriptで別の関数を呼び出すfunctionの書き方
- 【初心者向けGAS】時限式のイベントトリガーを設置して決まった時刻にBotを送信する方法
- 【初心者向けGAS】プロパティストアの概要とスクリプトプロパティの編集方法
- 【初心者向けGAS】スクリプトプロパティを操作してそのデータを取り出す方法
- 【初心者向けGAS】スプレッドシートのセル範囲の値を二次元配列として取得して取り扱う方法
- 【初心者向けGAS】Chatworkのメッセージ記法でBot送信するメッセージを装飾する方法
- 【初心者向けGAS】Google Apps Scriptのドキュメンテーションコメントの書き方
コメント
「JSDoc」のリンク先「http://usejsdoc.org/」が、
このサイトにアクセスできません
usejsdoc.org のサーバーの IP アドレスが見つかりませんでした。
となっていました。
できれば、正しい参照先を閲覧したいです。
CUTBOSSさん
コメントありがとうございます。
確かに、リンクが切れてしまっていますね…
おそらくこちらだと思いますので、ご参考くださいませ。
https://jsdoc.app/