Javascript 和代码文档
由 Mux 主办的 DEV 全球展示挑战赛：展示你的项目！
JavaScript 是一种符合 ECMAScript 规范的编程语言。它是一种高级语言，通常采用即时编译，并且支持多种编程范式。它具有动态类型、基于原型的面向对象特性以及一等函数。
为什么要编写代码文档？
如果你用 JavaScript 写了一些用于创建 HTML 表格的函数，你可以立即使用这些函数，也可以将它们交给其他开发者。编写代码时，一切都清晰明了，但一个月后，你可能就忘记了如何使用函数 A 或函数 B 了。函数 A 应该如何调用？它需要哪些参数？参数的格式应该是什么？
代码文档可以帮助你和其他开发者理解如何使用你编写的软件。有很多方法可以为一段代码编写文档。例如，你可以这样写：
- 使用代码的操作指南
- 仓库的 README 文件写得不错。
- 除了使用指南和 README 文件之外，源代码中的代码文档也极具价值。它与代码并列，有助于你在编辑器中编写 JavaScript 代码时避免错误。
考虑以下函数：
function generateTableHead(table, data) {
const thead = table.createTHead();
const row = thead.insertRow();
for (const i of data) {
const th = document.createElement("th");
const text = document.createTextNode(i);
th.appendChild(text);
row.appendChild(th);
}
}
`generateTableHead` 函数本身的意思已经很清楚了。`data` 参数没有明确说明它应该执行什么操作，也没有说明数据应该是什么。
如果我们查看函数体，就会发现 `data` 必须是一个数组。而 `table` 参数则没有明确说明它应该是一个字符串还是一个实际的 HTML 元素。
我们只需在函数前面添加一条注释即可：
/**
* Generates a table head
*/
function generateTableHead(table, data) {
const thead = table.createTHead();
const row = thead.insertRow();
for (const i of data) {
const th = document.createElement("th");
const text = document.createTextNode(i);
th.appendChild(text);
row.appendChild(th);
}
}
这是标准代码文档。`generateTableHead` 函数应该接受一个 HTMLTableElement 和一个数组作为参数。我们可以像这样为它们添加注解。
/**
* Generates a table head
* @param {HTMLTableElement} table - The target HTML table
* @param {Array} data - The array of cell header names
*/
function generateTableHead(table, data) {
const thead = table.createTHead();
const row = thead.insertRow();
for (const i of data) {
const th = document.createElement("th");
const text = document.createTextNode(i);
th.appendChild(text);
row.appendChild(th);
}
}
代码文档常常被忽视，甚至被认为浪费时间。优秀的代码应该能够自我解释。这在某种程度上是正确的。代码应该清晰、易懂、简洁。编写代码文档不仅对未来的自己有益，也能帮助你的同事。
文章来源：https://dev.to/mcube25/javascript-and-code-documentation-3hgo