【Uniapp】代码规范四：注释规范

1. 单行注释

• 使用双斜杠（//）进行单行注释，描述简单或短小的逻辑。

• 注释应放在代码行上方或右侧，保持整洁，避免行过长。

• 示例：

// 计算用户的年龄
const age = currentYear - birthYear; // 当前年份减去出生年份

2. 多行注释

• 使用斜杠星号（/* ... */）进行多行注释，描述复杂的逻辑或功能。

• 适用于需要较多说明的部分，应尽量避免冗长。

• 示例：

/*
 * 这个函数用于获取用户数据。
 * 它会向API发送请求，并处理响应。
 */
function fetchUserData() { ... }

3. 函数注释

• 在每个函数定义前添加注释，使用JSDoc格式说明其功能、参数和返回值。

• 需包含详细的描述，使用标准化的标签以提升可读性。

• 示例：

/**
 * 获取用户数据
 * @param {string} userId - 用户的ID
 * @returns {Promise<object>} - 返回用户数据的Promise
 */
async function getUserData(userId) { ... }

注释：

JSDoc是一种用于JavaScript代码注释的标准化格式，主要用于生成文档和提高代码的可读性。以下是JSDoc的详细说明，包括其基本语法和常用标签：
​
基本语法：JSDoc注释通常以/**开始，以*/结束，注释内容放在这两者之间。每个标签前使用@符号。
​
常用标签
​
1.@param：
描述函数参数的类型和意义。
格式：@param {type} name - description
示例：@param {string} userName - 用户的名称
​
2.@returns / @return：
描述函数的返回值类型和含义。
格式：@returns {type} - description
示例：@returns {boolean} - 返回是否成功
​
3.@example：
提供使用示例，帮助理解如何使用函数。
格式：@example 后接示例代码块。
示例：
/**
 * @example
 * const result = add(2, 3);
 * console.log(result);*/
 
4.@throws / @exception：
描述函数可能抛出的异常及其条件。
格式：@throws {type} - description
示例：@throws {Error} - 如果输入无效则抛出错误
​
5.@async：
标记一个函数为异步函数。
示例：
/**
@async
@returns {Promise<string>} - 返回数据的Promise */
​
6.@typedef：
定义一个自定义类型，可以用于描述复杂对象。
格式：
/**
 * @typedef {Object} User
 * @property {string} id - 用户ID
 * @property {string} name - 用户名称 */
​
7.@property：
描述对象的属性，通常与@typedef一起使用。
示例：@property {number} age - 用户年龄

4. 复杂逻辑注释

• 对于复杂的逻辑段，提供详细的上下文和实现思路，便于后续维护。

• 注释应简洁，专注于逻辑而非代码本身，避免冗长的解释。

• 示例：

/*
 * 此逻辑用于处理用户登录。
 * 首先验证用户凭证，若有效，则获取用户数据。
 * 否则返回错误信息。
 */
function login(username, password) { ... }

5. TODO 注释

• 使用 // TODO: 标记待完成的任务，以便后续开发人员能快速找到并处理。

• 示例：

// TODO: 实现用户认证逻辑

6. 警告注释

• 使用 // FIXME: 或 // NOTE: 标记潜在的问题或需要注意的事项，便于后续修复。

• 示例：

// FIXME: 这里的逻辑可能会导致错误

7. 注释风格

• 注释应简洁明了，使用清晰的语言，避免模糊的描述。
• 保持一致性，遵循团队内的注释风格，避免不同风格混用。

8. 避免多余注释

• 不要注释显而易见的代码，保持代码的自解释性，清晰的命名和结构可以减少注释的需求。
• 仅在需要时添加注释，确保注释内容有价值。

9. 总结

良好的注释规范能够极大地提高代码的可读性和可维护性，帮助开发人员在后续的开发中快速理解代码逻辑。团队应统一并推广这些规范，并在代码审查中严格执行，以确保高质量的代码文档。