在JavaScript开发过程中，规范的代码注释能大幅降低团队协作的成本，而函数返回值注解是注释体系中非常重要的一部分。很多开发者在编写函数时只关注参数注释，忽略了返回值的相关说明，导致后续调用函数时需要查看函数内部逻辑才能知道返回值类型，影响开发效率。
什么是JS返回值注解
JS返回值注解是指通过特定注释语法，明确标注函数执行后返回的值的类型、描述等信息的注释方式，目前行业内最常用的是JSDoc规范下的返回值注解。这类注解不会参与代码运行，主要是给开发者、IDE工具提供信息参考。
基础返回值注解语法
JSDoc中使用@returns或者@return标签来标注返回值，基础语法格式如下：
/**
* 计算两个数字的和
* @param {number} a 第一个加数
* @param {number} b 第二个加数
* @returns {number} 两个数字相加的结果
*/
function add(a, b) {
return a + b;
}
不同返回值类型的注解写法
返回基本类型值
当函数返回字符串、数字、布尔值等基本类型时，直接在@returns后标注对应的类型即可：
/**
* 检查用户是否成年
* @param {number} age 用户年龄
* @returns {boolean} 是否成年，true表示成年，false表示未成年
*/
function checkAdult(age) {
return age >= 18;
}
/**
* 获取用户欢迎语
* @param {string} name 用户名称
* @returns {string} 拼接后的欢迎语
*/
function getWelcome(name) {
return '欢迎你，' + name;
}
返回对象或数组类型
如果返回值是一个对象或者数组，可以标注具体结构，让调用方更清楚返回值的属性：
/**
* 获取用户信息
* @param {number} userId 用户ID
* @returns {Object} 用户信息对象
* @returns {number} return.id 用户ID
* @returns {string} return.name 用户名称
* @returns {number} return.age 用户年龄
*/
function getUserInfo(userId) {
// 模拟接口返回数据
return {
id: userId,
name: '张三',
age: 20
};
}
/**
* 获取用户角色列表
* @returns {string[]} 角色名称组成的数组
*/
function getRoles() {
return ['管理员', '普通用户'];
}
返回可能为null或undefined的情况
当函数可能返回null或者undefined时，需要用|分隔多种可能的返回值类型：
/**
* 根据ID查找用户
* @param {number} userId 用户ID
* @returns {Object|null} 找到则返回用户对象，未找到则返回null
*/
function findUser(userId) {
const users = [{id: 1, name: '张三'}, {id: 2, name: '李四'}];
const target = users.find(item => item.id === userId);
return target || null;
}
返回值注解的实际意义
- 提升代码可读性：调用方不需要查看函数内部实现，就能通过注解知道返回值的类型和含义，减少理解成本。
- IDE类型提示：主流IDE如VS Code可以识别JSDoc注解，在调用函数时自动提示返回值类型，减少类型使用错误。
- 便于代码维护：后续修改函数返回值时，只需要同步修改注解即可，避免调用方因返回值变更出现兼容问题。
- 生成文档依据：可以通过工具根据JSDoc注解自动生成API文档，返回值注解是文档中返回值说明的核心来源。
返回值注解的注意事项
首先，注解内容需要和函数实际返回值保持一致，不能标注返回number但函数实际返回string，否则会误导开发者。其次，不需要对过于简单的函数强行加返回值注解，比如只有一行返回基本运算结果的函数，代码本身已经足够清晰时可以不加。最后，如果项目使用了TypeScript，也可以结合TS的类型定义来标注返回值，和JSDoc注解的作用类似，可以根据项目技术栈选择使用。