在JavaScript的ES6类开发中，为类方法添加注解可以清晰说明方法的功能、参数要求、返回值类型等信息，降低代码维护成本。注解本身不影响代码执行，主要用于代码提示和逻辑说明。
JS类方法注解的基础规范
JS中没有官方的注解语法，通常我们使用多行注释/** */的形式来编写注解，这种格式可以被大部分IDE识别，提供代码提示功能。基础的类方法注解需要包含方法功能描述、参数说明、返回值说明三个核心部分。
基础注解结构示例
/**
* 计算两个数字的和
* @param {number} a 第一个加数
* @param {number} b 第二个加数
* @returns {number} 两个数字的和
*/
add(a, b) {
return a + b;
}
常用注解标签说明
注解中通过特定的标签来标注不同信息，以下是类方法注解中常用的标签：
- @param：标注方法参数的类型和说明，格式为
@param {类型} 参数名 参数描述 - @returns：标注方法返回值的类型和说明，格式为
@returns {类型} 返回值描述 - @throws：标注方法可能抛出的异常类型和触发场景
- @deprecated：标记方法已废弃，说明废弃原因和替代方案
- @static：标记该方法是静态方法
不同场景的类方法注解示例
普通实例方法注解
实例方法是类中定义的最常见方法，注解需要明确参数和返回值的类型约束。
class UserService {
/**
* 根据用户ID查询用户详情
* @param {string} userId 用户唯一标识
* @returns {Object} 用户详情对象，包含id、name、age字段
* @throws {Error} 当用户ID不存在时抛出错误
*/
getUserById(userId) {
if (!userId) {
throw new Error('用户ID不能为空');
}
// 模拟查询逻辑
return {
id: userId,
name: '测试用户',
age: 25
};
}
}
静态方法注解
静态方法不需要实例化类即可调用，注解中需要添加@static标签说明。
class MathUtil {
/**
* 计算数组中所有数字的平均值
* @static
* @param {number[]} arr 数字数组
* @returns {number} 数组平均值，数组为空时返回0
*/
static average(arr) {
if (!arr || arr.length === 0) {
return 0;
}
const sum = arr.reduce((acc, cur) => acc + cur, 0);
return sum / arr.length;
}
}
废弃方法注解
当类中的方法需要被替换时，使用@deprecated标签标注，引导开发者使用新的方法。
class DataHandler {
/**
* 获取本地存储的数据（已废弃）
* @deprecated 自v2.0版本起废弃，请使用getStorageData方法替代
* @param {string} key 存储键名
* @returns {string|null} 存储的数据，不存在时返回null
*/
getLocalData(key) {
return localStorage.getItem(key);
}
/**
* 获取本地存储的数据
* @param {string} key 存储键名
* @returns {string|null} 存储的数据，不存在时返回null
*/
getStorageData(key) {
return localStorage.getItem(key);
}
}
注解书写注意事项
编写类方法注解时需要注意以下几点：
- 注解描述要简洁准确，避免冗余内容，核心信息优先展示
- 参数类型和返回值类型要符合JS的实际类型，复杂类型可以标注具体结构
- 如果方法没有返回值，可以用
@returns {void}标注 - 多个参数时每个参数单独写一行
@param标签，不要合并
良好的注解习惯可以让代码可读性大幅提升，尤其是在团队多人协作的项目中，清晰的类方法注解能减少很多沟通成本。
JavaScript类方法注解JS_annotationES6_class修改时间：2026-06-10 11:12:14