在 JavaScript 中是否有指定作者、日期或代碼來源的約定？

Question

我想指定外部函數的來源（例如這里來自 StackOverflow ）。 我還想將我的姓名、日期和網站添加到我自己的功能中。

我當然可以按照我想要的方式將所有內容放在評論中。 但是我應該遵循某些約定嗎？ 也許甚至機器可讀？

Answer 1

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.
 */

Answer 2

沒有官方的方式來指定這一點。 至少沒有一條真道。

話雖如此，最廣泛接受的是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）將為您提供 hover 上的 function 的 JSDoc。

但是，還有其他工具可以使用 JSDoc 或其子集。 他們可能會生成文檔，或者根據為@param和@return指定的內容或其他任務執行類型檢查。

還值得注意的是，您不需要任何工具即可使用 JSDoc。 即使它永遠不會被使用，您也可以直接在源代碼中編寫它。 它仍然可以被其他能夠理解它的人閱讀。 即使這是他們第一次遇到文檔樣式，它也足夠直截了當，易於理解。