如何为 Google Apps 脚本编写适当的文档？

Question

我是一名正在学习编码的营销人员。目前我选择的主要武器是 Google Apps Scripts。随着我深入研究并为其他人编写代码，我想确保我的代码有据可查。在 GAS 之前，我从 Python 开始，PEP-8 对此有明确的指导方针。有没有类似的 GAS 指南？

我目前如何记录函数（除了具有清晰的变量名称和一些内联 cmets：

在每个脚本的顶部：

/**
 * @name The name of the script
 *
 * @fileoverview The overview and expected outcome 
 *
 * @author my name and e-mail address
 *
 * @version 1.0
 *
 * @changelog
 * - version 1.0
 *   - Released initial version.
 */

每个函数定义下面：

function buildResultsObject(contactList) {
  /**
   * Parses the contactList to create
   * an object per countryCategory ID
   *
   * The data array in the object is initialised
   * to be empty and will be filled when the 
   * data is parsed with another function.
   *
   * @param {contactList} the values from the contact list sheet as a 2-level array
   * @returns {Object} results
   *
   * Example structure of results:
   * 
   *  {'AUBAK':
   *    {
   *    'country; 'AU'
   *    'category': 'BAK'
   *    'email': 'a@b.com',
   *    'data': []
   *    }
   *  }
   *
   */

  code here
}

我的问题：

• 我应该这样做还是有更好的方法？
• cmets 中的@ 标签到底有什么作用？例如，我注意到使用 @name 参数，我实际上是在更改可以在菜单栏下方的“选择函数”下拉菜单中运行的脚本的名称。

Answer 1

以下链接就足够了：

https://google.github.io/styleguide/jsguide.html

上面链接的指南中的第 7 章涵盖了您需要了解的所有内容。

但您还应该查看应用程序脚本参考文档（和插件文档），因为有一些与 oauth 范围和插件相关的 GAS 特定 @tags 仅记录在那里。