【初心者向けGAS】Google Apps Scriptのドキュメンテーションコメントの書き方


comment

photo credit: kristin wolff interview via photopin (license)

みなさん、こんにちは!
タカハシ(@ntakahashi0505)です。

初心者向けGoogle Apps Script入門、名言Botを作るシリーズをお送りしています。

前回の記事はコチラ。

【初心者向けGAS】チャットワークのメッセージ記法でBot送信するメッセージを装飾する方法
初心者向けGoogle Apps Scriptのシリーズとしてチャットワークを使った名言Botを作る方法をお伝えしています。今回は、チャットワークの通知を装飾するメッセージ記法を使う方法をお伝えしています。

チャットワークのメッセージ記法を使ってメッセージの装飾をする方法についてお伝えしました。

さて、今回でいよいよこのシリーズも最終回です。

スクリプト自体はいじらないのですが、あとで見返すとき、メンテナンスするときに備えて、ドキュメンテーションコメントを加えていきます。

では、Google Apps Scriptのドキュメンテーションコメントの書き方です。

行ってみましょう!

ドキュメンテーションコメントとは

ドキュメンテーションコメントとは、関数を説明するためのコメントのことです。

関数の宣言の直前に記載する「/**」ではじまり「*/」で終わるコメントで、関数の役割や引数、戻り値などについての情報を記載します。

Google Apps Scriptの公式ドキュメントから拝借して、一例を示すと以下のようなものです。

「@」ではじまるタグを指定することで、スプレッドシートのカスタム関数やライブラリとして利用したときに、補完の候補としたり、詳細情報を表示したりすることができます。

カスタム関数やライブラリとして使わなくても、統一してドキュメンテーションコメントを入れておくことで

  • 後で見返したり、再利用したりするとき
  • 他のメンバーと共同作業するとき
  • 関数のメンテナンスをするとき

などに関数の役割をすぐに把握することができますので、ぜひ全ての関数に記入するようにしてくださいね。

使用できるタグとデータ型について

GASのドキュメンテーションコメントの書き方は、JavaScriptで一般的に用いられている書式であるJSDocがベースになっています。

しかし、GASの場合、使用できるタグは、以下の3つのみに限られています。

タグ 説明
@param 引数の {データ型} と説明
@return 戻り値の {データ型} と説明
@customfunction スプレッドシートのカスタム関数として使う(スプレッドシートのコンテナバインドのときのみ

型の指定については、主要なものは以下の通りです。

  • 数値:{number}
  • 文字列:{string}
  • 真偽値:{boolean}
  • オブジェクト:{Object}
  • オブジェクトの配列:{Object[]}

名言Botスクリプトのドキュメンテーションコメント

前回までに作成した名言Botのスクリプトにドキュメンテーションコメントを付与すると以下のようになります。

これくらいの規模であればコメントなんかイラン!って思われるかも知れませんが、ドキュメンテーションコメントをパッと見るだけで

  • スプレッドシートを使う
  • チャットワークを使う
  • Botなのでトリガーが設置されているかも

などといった情報を仕入れることができます。

急がば回れ、ここは手を抜かずに全ての関数にドキュメンテーションコメントを入れておいたほうが良いでしょう。

まとめ

以上、Google Apps Scriptのドキュメンテーションコメントの書き方についてお伝えしました。

繰り返しになりますが、この小さな手間が後々大きく跳ね返ってきますので、面倒くさがらずに書いてくださいね。

さて、これにてGASによる名言Botの作成シリーズについては完了です。

GASでできることは、コレ以外にも本当に幅広く、その可能性は無限といっても良いほどです。

ぜひ、色々なアイデアを考案して実現してみてくださいね!

連載目次:超初心者向けGASでBotを作りながら基礎を学ぶ

Google Apps Script(GAS)をはじめるためのメリットは山程ありますが、何を作ったらいいの?と悩んでしまうこともありますよね。そんな時に、おすすめしたいのが「Bot」の作成です。このシリーズでは、超初心者向けにGASでBotを作る方法を題材としながら、GASプログラミングの一通りの流れと書き方について学んでいきます。
  1. 【初心者向けGAS】本当の最初の一歩!スクリプトエディタでプロジェクトを開く
  2. 【初心者向けGAS】はじめてのスクリプトを作成し、保存し、実行する
  3. 【初心者向けGAS】プログラミングに必須の変数の使い方とデータ型について
  4. 【初心者向けGAS】ログを表示するLogger.logの使い方
  5. 【初心者向けGAS】スクリプト実行時の「承認」でびっくりしないために
  6. 【初心者向けGAS】Spreadsheetサービスの「オブジェクト」の基礎の基礎を知ろう
  7. 【初心者向けGAS】スプレッドシートのシートを取得する2つの方法
  8. 【初心者向けGAS】スプレッドシートのセル・セル範囲とその値を取得する方法
  9. 【初心者向けGAS】for文を使ったスプレッドシートの繰り返しの超基本
  10. 【初心者向けGAS】条件分岐をするif文の使い方の超基本
  11. 【初心者向けGAS】スプレッドシートのセルに値を入力する基礎の基礎
  12. 【初心者向けGAS】条件に応じてループを制御する2つの方法~break文とwhile文~
  13. 【初心者向けGAS】スプレッドシートのセル範囲を行数・列数を使って取得する
  14. 【初心者向けGAS】スプレッドシートのセル範囲をクリアするいくつかの方法
  15. 【初心者向けGAS】Google Apps ScriptでWeb APIを活用するための基礎知識
  16. 【初心者向けGAS】面倒なことはライブラリに任せよう!その概要と追加の方法
  17. 【初心者向けGAS】チャットワークのマイチャットにメッセージを送る最も簡単な例
  18. 【初心者向けGAS】Google Apps Scriptで別の関数を呼び出すfunctionの書き方
  19. 【初心者向けGAS】時限式のイベントトリガーを設置して決まった時刻にBotを送信する方法
  20. 【初心者向けGAS】プロパティストアの概要とスクリプトプロパティの編集方法
  21. 【初心者向けGAS】スクリプトプロパティを操作してそのデータを取り出す方法
  22. 【初心者向けGAS】スプレッドシートのセル範囲の値を二次元配列として取得して取り扱う方法
  23. 【初心者向けGAS】チャットワークのメッセージ記法でBot送信するメッセージを装飾する方法
  24. 【初心者向けGAS】Google Apps Scriptのドキュメンテーションコメントの書き方

The following two tabs change content below.
株式会社プランノーツ代表、コミュニティ「ノンプロ研」主宰。1976年こどもの日生まれ。東京板橋区在住。「ITで日本の『働く』の価値を上げる!」をテーマに、VBA&GASの開発、講師、執筆などをしております。→詳しいプロフィールはコチラ ★ご依頼・ご相談はお気軽にどうぞ!→お問い合わせはコチラ ★フォロー頂ければ嬉しいです。

コメント