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

Question

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

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

Answer 1

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

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

/**
 * Function that returns a random number
 * @author Jon Skeet
 * @see {@link https://stackoverflow.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 或其子集。他们可以生成文档，或根据为@paramand@return或其他任务指定的内容执行类型检查。

还值得注意的是，您不需要任何工具即可使用 JSDoc。即使它永远不会被使用，您也可以直接在源代码中编写它。它仍然可以被其他能够理解它的人阅读。即使这是他们第一次遇到文档样式，它也足够直截了当，易于理解。

Answer 2

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

例子：

/**
 * @author Some Guy <example@example.com>
 * @see {@link https://jsdoc.app/tags-description.html} for further information.
 * @description How to use JSDoc to tag javascript.
 */