是否有在 JavaScript 中指定作者、日期或代码来源的约定？

Posted 2023-02-21

【中文标题】是否有在 JavaScript 中指定作者、日期或代码来源的约定？

【英文标题】：Is there a convention for specifying the author, date, or source of code in JavaScript?

【发布时间】：2021-12-30 13:32:21

【问题描述】：

我想指定外部函数的来源（例如这里来自 *** ????）。我还想将我的姓名、日期和网站添加到我自己的函数中。

我当然可以按照我想要的方式将所有内容放在评论中。但是我应该遵循某些约定吗？甚至是机器可读的？

【问题讨论】：

jsdoc 是最接近的。

【参考方案1】：

没有官方方法来指定这一点。至少没有一条真道。

话虽如此，最广泛接受的是JSDoc comments。你需要用/**（两个星号）开始一个块注释，然后你可以使用特殊的JSDoc语法来解释你的源代码@author和@see：

/**
 * Function that returns a random number
 * @author Jon Skeet
 * @see @link https://***.com/a/11373465
 * 
 * @param number min - minimum bound (inclusive)
 * @param number max - maximum bound (inclusive)
 * @return string - uniformly distributed integer within the range as a string 
 */
function rand(min, max)
   return (Math.floor(Math.random() * (max - min + 1)) + min).toFixed(0);

---

甚至可能是机器可读的？

JSDoc 是机器可读的。有许多使用它的工具。最值得注意的是，许多标准 javascript 编辑器（如 Visual Studio Code）将为您提供悬停功能的 JSDoc。

但是，还有其他工具可以使用 JSDoc 或其子集。他们可能会根据为@param 和@return 或其他任务指定的内容生成文档或执行类型检查。

还值得注意的是，您不需要 拥有任何工具来使用 JSDoc。即使它永远不会被使用，您也可以直接在源代码中编写它。它仍然可以被其他能够理解它的人阅读。即使他们是第一次遇到文档风格，也足够简单易懂。

【参考方案2】：

JSDoc 通常用于为 javascript 代码指定元数据，并可用于自动生成文档。见：https://jsdoc.app/about-getting-started.html

例子：

/**
 * @author Some Guy <[e-mail]>
 * @see @link https://jsdoc.app/tags-description.html for further information.
 * @description How to use JSDoc to tag javascript.
 */