JavaScript中@param注解的含义及Node.js代码示例解析

Hey there! Let's break down what the @param annotation does in JavaScript, using that multisig wallet function you shared as a concrete example.

先搞懂@param到底是什么 #

@param是JSDoc（JavaScript的标准文档注释规范）里的核心注解之一。简单说，它就是给函数参数写的"说明书"——不用读函数内部逻辑，其他开发者（包括半年后的你自己）一眼就能知道：这个函数需要什么参数、参数是什么类型、参数用来干嘛。

结合你的多签钱包代码解析 #

先把你的代码整理成更规范的格式：

/**
 * Create multi signature wallet function
 * @param account {String} account name
 * @returns {String} Return multisig wallet address
 */
const createMultiSigWallet = async(account) => {
 if (!account) throw new Error('Account name is required.');
 let keys = [];
 await keys.push(await createWallet());
 await keys.push(await createWallet());
 return client.execute('addmultisigaddress', [2, keys, account]);
};

看这段注释里的@param account {String} account name，它拆成三个关键部分：

• account：对应函数定义里的参数名async(account) => {...}，明确告诉大家这个参数的变量名是什么。
• {String}：标注参数的类型——这里要求必须传入字符串类型，不能是数字、对象或者其他类型。主流IDE（比如VS Code）会利用这个信息做类型提示，提前帮你排查错误。
• account name：用大白话解释参数的作用——这是要和创建的多签钱包绑定的账户名称。

这个@param到底有啥实际价值？ #

1. 降低理解成本：其他开发者想用这个函数时，扫一眼注释就知道要传什么，不用去翻函数里的throw new Error才发现account是必填项。
2. 工具赋能：IDE会读取JSDoc信息，输入函数名时自动弹出参数提示，甚至如果你传了非字符串类型，会直接给你标红提醒。
3. 维护便捷：以后如果要修改参数规则（比如允许传入对象类型），只要更新@param的注释，所有依赖这个函数的人都能立刻看到变化。

内容的提问来源于stack exchange，提问作者Saif Ali