admin/tools-show
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update

Browse Source
This commit is contained in:
admin
2026-04-11 20:46:55 +08:00
parent e6c2d76238
commit e04405d0bc
70 changed files with 10438 additions and 332 deletions
Download Patch File Download Diff File Expand all files Collapse all files

257
.agents/skills/code-commentator/SKILL.md Normal file
View File

@@ -0,0 +1,257 @@
---
name: code-commentator
description: 代码注释补充与规范化专家，自动识别代码文件类型，为函数、类、方法、属性等代码元素添加专业双语注释。当用户提及"添加注释"、"补充注释"、"规范化注释"、"代码注释"、"annotate code"、"add comments"或需要为代码添加文档注释时使用本技能。本技能也可被其他技能（如 executing-plans）在代码完成后自动调用。
license: MIT
metadata:
version: "1.2.0"
---
# 代码注释补充与规范化技能
本技能提供代码注释的系统性补充与规范化处理能力，自动识别代码文件类型，应用相应的注释规范，确保生成的注释准确、完整且符合双语要求。
## 触发条件
当检测到以下情况时，主动激活此技能：
**用户直接调用**：
- 用户提及添加或补充注释："添加注释"、"补充注释"、"增加注释"
- 用户提及规范化注释："规范化注释"、"统一注释风格"、"注释规范"
- 用户提及代码注释需求："给代码加注释"、"代码缺少注释"、"注释不完整"
- 用户提及特定注释类型："函数注释"、"类注释"、"JSDoc"、"docstring"
- 英文触发词："add comments"、"annotate code"、"code documentation"、"JSDoc"
**其他技能自动调用**：
- `executing-plans` 技能在任务完成后自动调用（如果代码需要注释）
- 在测试通过后、代码提交前的自动化流程中
---
## 被其他技能调用
当被 `executing-plans` 或其他技能调用时：
**接收参数**：
- `target_files`：需要添加注释的文件路径列表（必需）
- `comment_priority`：注释优先级（可选：high/medium/low）
- `focus_areas`：重点注释区域（可选：如"公共API"、"核心逻辑"）
**执行模式**：
- 跳过用户确认，直接执行
- 使用默认的双语注释格式
- 自动识别代码复杂度，智能添加注释
- 完成后返回处理结果摘要
---
## 绝对禁止事项 ⚠️
**严禁修改任何代码内容**。本技能只能添加或修改注释，不得：
- ❌ 修改代码逻辑
- ❌ 修改变量名、函数名、类名等标识符
- ❌ 修改代码结构（如添加、删除、重排代码行）
- ❌ 修改代码格式（如缩进、换行、空格）
**唯一允许的操作**：为代码添加注释或修改现有注释。
---
## 双语注释要求
所有注释必须同时包含**中英文双语说明**，格式为：
- 英文描述在前
- 空行分隔
- 中文描述在后
---
## 注释格式参考
详细的多语言注释格式示例已迁移到 references 目录：
| 参考文件 | 内容 |
| ------------------------------------------------------- | ------------------------------ |
| [comment-formats.md](references/comment-formats.md) | 各种编程语言的注释格式代码示例 |
| [writing-style.md](references/writing-style.md) | 语气与口吻规范、语言语法要求 |
| [quality-checklist.md](references/quality-checklist.md) | 注释质量验证清单 |
**重要**：添加注释前，先阅读 [comment-formats.md](references/comment-formats.md) 确保使用正确的语言格式。
---
## 核心注释原则
### 必须添加多行注释的元素
以下代码元素**必须**添加多行文档注释：
- ✅ 函数/方法
- ✅ 类/结构体/接口
- ✅ 公共属性/字段
- ✅ 枚举及其成员
- ✅ 类型定义
- ✅ 模块/命名空间
### 需要评估是否添加注释
仅在代码逻辑不够直观时才添加单行注释：
- ⚠️ 复杂的条件分支逻辑
- ⚠️ 复杂的循环结构
- ⚠️ 复杂的表达式
- ⚠️ 重要的变量声明（用途不明显时）
### 不需要添加注释的情况
代码本身已足够清晰，无需添加注释：
- ❌ 简单的条件判断（如 `if (isValid)`）
- ❌ 简单的循环（如 `for (const item of items)`）
- ❌ 变量名已清晰表达用途的声明（如 `const userName = user.name`）
- ❌ 标准的 getter/setter 方法
- ❌ 一目了然的赋值语句
### 判断标准
**添加注释前，先问自己**：
1. 不看注释，能否快速理解这段代码的意图？
2. 代码命名是否足够清晰？
3. 注释是否提供了代码本身无法表达的信息？
如果以上问题的答案表明代码已足够清晰，则不需要添加注释。
---
## 注释插入规则
| 元素类型 | 插入位置 | 要求 |
| ------------- | ------------------ | ------------------ |
| 函数/方法注释 | 紧贴在函数声明上方 | 不留空行 |
| 类注释 | 紧贴在类声明上方 | 不留空行 |
| 属性注释 | 紧贴在属性声明上方 | 不留空行 |
| 单行注释 | 放在代码行上方 | 与代码保持相同缩进 |
---
## 函数/方法注释要点
函数/方法注释必须包含：
1. **功能描述**：清晰描述函数的功能和用途
2. **入参说明**：每个参数的类型和用途
3. **出参说明**：返回值的类型和含义
4. **异常说明**：可能抛出的异常及其条件（如有）
5. **使用示例**：至少一个基本使用示例
### 联合类型参数
当参数为联合类型时，**必须**详细说明每个类型：
```typescript
@param input - The input data to process. Can be:
- `string`: A string value to parse / 要解析的字符串值
- `Buffer`: A buffer containing raw data / 包含原始数据的缓冲区
- `ReadableStream`: A stream to read data from / 要读取数据的流
```
### 多种传参方式
支持多种传参方式时，提供**不同场景的使用示例**：
```typescript
@example
// Create user with name only
const user = createUser('John');
// Create user with options object
const user = createUser({ name: 'John', age: 25, email: 'john@example.com' });
```
---
## 执行流程
### 文件扫描流程
1. 接收用户指定的文件或目录
2. 递归扫描所有代码文件
3. 按语言类型分组处理
4. 生成处理计划
### 单文件处理流程
1. 读取文件内容
2. 解析代码结构（AST 或正则匹配）
3. 识别需要注释的代码元素
4. 检查现有注释的完整性
5. 生成符合规范的注释
6. 将注释插入到正确位置
7. 写入更新后的文件
### 进度报告格式
处理过程中实时报告进度：
```markdown
## 注释处理进度
### 已完成 (3/10)
- ✅ src/utils/helper.ts (添加了 5 个函数注释)
- ✅ src/models/user.ts (添加了 2 个类注释, 8 个属性注释)
- ✅ src/api/client.ts (添加了 3 个函数注释)
### 处理中
- 🔄 src/services/auth.ts
### 待处理 (6/10)
- ⏳ src/config/index.ts
- ...
```
---
## 快速参考
### 注释格式速查
```typescript
/**
* English description of the function.
*
* 中文描述函数的功能。
*
* @param paramName - English description / 中文描述
* @returns English description / 中文描述
* @throws {ErrorType} English description / 中文描述
* @example
* const result = functionName('value');
*/
function functionName(paramName: string): Result {}
```
### 注意事项速记
1. **只添加注释**：严禁修改任何代码内容
2. **保持一致性**：同一文件内注释风格必须一致
3. **准确性优先**：注释内容必须准确反映代码功能
4. **避免过度注释**：如果代码本身足够清晰，则不需要添加注释
5. **简洁明了**：注释应有实际价值
6. **示例可运行**：所有使用示例必须是可运行的代码
---
## 参考文档
- 📄 [comment-formats.md](references/comment-formats.md) - 详细格式示例
- 📄 [writing-style.md](references/writing-style.md) - 写作风格指南
- 📄 [quality-checklist.md](references/quality-checklist.md) - 质量验证清单

409
.agents/skills/code-commentator/references/comment-formats.md Normal file
View File

@@ -0,0 +1,409 @@
# 注释格式参考指南
本文档提供各种编程语言的注释格式详细示例，供在添加注释时参考。
## 目录
- [编程语言识别](#编程语言识别)
- [多行注释格式](#多行注释格式)
- [单行注释格式](#单行注释格式)
- [注释文本格式](#注释文本格式)
---
## 编程语言识别
根据文件扩展名识别编程语言，选择对应的注释风格：
| 语言 | 文件扩展名 | 多行注释风格 | 单行注释风格 |
| --------------------- | -------------------------------------------- | ------------------------------ | ------------ |
| JavaScript/TypeScript | `.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs` | `/** ... */` | `// ...` |
| Python | `.py` | `""" ... """` 或 `''' ... '''` | `# ...` |
| Java | `.java` | `/** ... */` | `// ...` |
| C/C++ | `.c`, `.cpp`, `.h`, `.hpp` | `/** ... */` | `// ...` |
| Go | `.go` | `/** ... */` | `// ...` |
| Rust | `.rs` | `/// ...` (文档注释) | `// ...` |
| PHP | `.php` | `/** ... */` | `// ...` |
| Ruby | `.rb` | `=begin ... =end` | `# ...` |
| Swift | `.swift` | `/** ... */` | `// ...` |
| Kotlin | `.kt`, `.kts` | `/** ... */` | `// ...` |
| C# | `.cs` | `/** ... */` | `// ...` |
| Scala | `.scala` | `/** ... */` | `// ...` |
| Lua | `.lua` | `--[[ ... --]]` | `-- ...` |
| Shell | `.sh`, `.bash` | `: ' ... '` | `# ...` |
---
## 多行注释格式
### JavaScript/TypeScript 格式
```typescript
/**
* English description of the function.
*
* 中文描述函数的功能。
*
* @param paramName - English description / 中文描述
* @returns English description / 中文描述
* @throws {ErrorType} English description / 中文描述
* @example
* // Basic usage
* const result = functionName('value');
*
* // With optional parameter
* const result = functionName('value', { option: true });
*/
function functionName(paramName: string, options?: Options): Result {
// implementation
}
```
### Python 格式
```python
"""
English description of the function.
中文描述函数的功能。
Args:
param_name (str): English description / 中文描述
Returns:
Result: English description / 中文描述
Raises:
ErrorType: English description / 中文描述
Example:
>>> # Basic usage
>>> result = function_name('value')
>>>
>>> # With optional parameter
>>> result = function_name('value', option=True)
"""
def function_name(param_name: str, options: Optional[Options] = None) -> Result:
# implementation
```
### Java 格式
```java
/**
* English description of the method.
*
* 中文描述方法的功能。
*
* @param paramName English description / 中文描述
* @return English description / 中文描述
* @throws ExceptionType English description / 中文描述
* @example
* // Basic usage
* Result result = methodName("value");
*
* // With optional parameter
* Result result = methodName("value", options);
*/
public Result methodName(String paramName, Options options) {
// implementation
}
```
### Go 格式
```go
// FunctionName English description of the function.
//
// 中文描述函数的功能。
//
// Parameters:
// - paramName: English description / 中文描述
//
// Returns:
// - result: English description / 中文描述
//
// Example:
//
// // Basic usage
// result := FunctionName("value")
//
// // With optional parameter
// result := FunctionName("value", options)
func FunctionName(paramName string, options *Options) *Result {
// implementation
}
```
### Rust 格式
````rust
/// English description of the function.
///
/// 中文描述函数的功能.
///
/// # Arguments
///
/// * `param_name` - English description / 中文描述
///
/// # Returns
///
/// English description / 中文描述
///
/// # Errors
///
/// Returns an error if...
///
/// # Examples
///
/// ```
/// // Basic usage
/// let result = function_name("value");
///
/// // With optional parameter
/// let result = function_name("value", Some(options));
/// ```
pub fn function_name(param_name: &str, options: Option<Options>) -> Result<Result, Error> {
// implementation
}
````
### PHP 格式
```php
/**
* English description of the function.
*
* 中文描述函数的功能。
*
* @param string $paramName English description / 中文描述
* @param array|null $options English description / 中文描述
* @return Result English description / 中文描述
* @throws ExceptionType English description / 中文描述
* @example
* // Basic usage
* $result = functionName('value');
*
* // With optional parameter
* $result = functionName('value', ['option' => true]);
*/
function functionName(string $paramName, ?array $options = null): Result {
// implementation
}
```
### Ruby 格式
```ruby
=begin
English description of the method.
中文描述方法的功能。
Parameters:
- param_name: English description / 中文描述
- options: English description / 中文描述
Returns:
- result: English description / 中文描述
Example:
# Basic usage
result = method_name('value')
# With optional parameter
result = method_name('value', option: true)
=end
def method_name(param_name, options = {})
# implementation
end
```
### Swift 格式
````swift
/// English description of the function.
///
/// 中文描述函数的功能.
///
/// - Parameters:
/// - paramName: English description / 中文描述
/// - options: English description / 中文描述
/// - Returns: English description / 中文描述
/// - Throws: English description / 中文描述
///
/// ## Example
/// ```swift
/// // Basic usage
/// let result = functionName("value")
///
/// // With optional parameter
/// let result = functionName("value", option: true)
/// ```
func functionName(paramName: String, options: Options? = nil) throws -> Result {
// implementation
}
````
### Kotlin 格式
```kotlin
/**
* English description of the function.
*
* 中文描述函数的功能。
*
* @param paramName English description / 中文描述
* @param options English description / 中文描述
* @return English description / 中文描述
* @throws ExceptionType English description / 中文描述
*
* @example
* // Basic usage
* val result = functionName("value")
*
* // With optional parameter
* val result = functionName("value", Options())
*/
fun functionName(paramName: String, options: Options? = null): Result {
// implementation
}
```
---
## 单行注释格式
### 短描述格式
```typescript
// english description / 中文描述
if (condition) {
}
// english description / 中文描述
const variable = value;
```
### 长描述格式
```typescript
// This is a longer english description that explains
// the purpose of the following code block.
//
// 这是较长的中文描述，解释以下代码块的用途。
if (complexCondition) {
// english description / 中文描述
doSomething();
}
```
### Python 单行注释
```python
# english description / 中文描述
if condition:
pass
# This is a longer english description that explains
# the purpose of the following code block.
#
# 这是较长的中文描述，解释以下代码块的用途。
for item in items:
# english description / 中文描述
process(item)
```
---
## 特殊注释场景
### 联合类型参数处理
当参数类型为联合类型时，使用无序列表详细说明每个类型：
```typescript
/**
* Processes the input data.
*
* 处理输入数据。
*
* @param input - The input data to process. Can be:
* - `string`: A string value to parse / 要解析的字符串值
* - `Buffer`: A buffer containing raw data / 包含原始数据的缓冲区
* - `ReadableStream`: A stream to read data from / 要读取数据的流
* @returns The processed result / 处理后的结果
* @example
* // Process a string
* const result = process('hello');
*
* // Process a buffer
* const result = process(Buffer.from('hello'));
*/
function process(input: string | Buffer | ReadableStream): Result {}
```
### 支持多种传参方式的函数
对于支持多种传参类型或传参个数的函数，需提供不同场景的使用示例：
```typescript
/**
* Creates a new user instance.
*
* 创建新的用户实例。
*
* @param nameOrOptions - Can be:
* - `string`: The user's name / 用户名称
* - `UserOptions`: Full user configuration object / 完整的用户配置对象
* @param age - User's age (required when first param is string) / 用户年龄（第一个参数为字符串时必填）
* @returns The created user instance / 创建的用户实例
* @example
* // Create user with name only
* const user = createUser('John');
*
* // Create user with name and age
* const user = createUser('John', 25);
*
* // Create user with options object
* const user = createUser({ name: 'John', age: 25, email: 'john@example.com' });
*/
function createUser(nameOrOptions: string | UserOptions, age?: number): User {}
```
---
## 注释文本格式
### 换行规则
注释文本应在100个字符左右处换行（长链接或表格等特殊内容除外）：
```typescript
/**
* This is a very long description that needs to be wrapped at approximately
* 100 characters to maintain readability and consistency across the codebase.
*
* 这是一个很长的描述，需要在约100个字符处换行，以保持代码库的可读性和一致性。
*/
```
### 中英文分隔
双语注释中，英文描述在前，中文描述在后，中间用空行分隔：
```typescript
/**
* English description comes first.
*
* 中文描述紧随其后。
*/
```
### 参数描述格式
参数描述使用斜杠分隔中英文：
```typescript
@param paramName - English description / 中文描述
```

230
.agents/skills/code-commentator/references/quality-checklist.md Normal file
View File

@@ -0,0 +1,230 @@
# 注释质量检查清单
本文档提供注释添加后的质量验证清单，用于确保注释符合规范要求。
## 目录
- [注释完整性检查](#注释完整性检查)
- [注释内容检查](#注释内容检查)
- [注释格式检查](#注释格式检查)
- [代码完整性检查](#代码完整性检查)
---
## 注释完整性检查
检查是否所有必需的代码元素都已添加注释：
### 函数/方法
- [ ] 所有公共函数都有多行注释
- [ ] 所有私有函数都有注释（如果复杂）
- [ ] 异步函数标记清晰
### 类/结构体
- [ ] 所有公共类都有多行注释
- [ ] 抽象类标记清晰
- [ ] 泛型类型参数有说明
### 属性/字段
- [ ] 所有公共属性都有注释
- [ ] 静态属性有说明
- [ ] 常量有用途说明
### 枚举
- [ ] 枚举本身有注释
- [ ] 所有枚举成员都有注释
- [ ] 每个成员的取值含义清晰
### 类型定义
- [ ] 接口/类型有注释
- [ ] 所有属性有说明
- [ ] 泛型参数有说明
---
## 注释内容检查
### 功能描述
- [ ] 功能描述清晰准确
- [ ] 不重复代码已表达的信息
- [ ] 描述了"做什么"而非"怎么做"
### 参数说明
- [ ] 每个参数都有说明
- [ ] 参数类型标注正确
- [ ] 联合类型参数有详细说明每个类型
- [ ] 可选参数标注清晰
- [ ] 参数的约束条件有说明
### 返回值说明
- [ ] 返回值类型正确
- [ ] 返回值的含义清晰
- [ ] 特殊情况（null、undefined）有说明
### 异常说明
- [ ] 所有可能抛出的异常都有说明
- [ ] 异常发生条件清晰
- [ ] 异常处理建议（如果有）
### 使用示例
- [ ] 至少包含一个基本使用示例
- [ ] 示例代码可运行
- [ ] 复杂函数有多个示例
- [ ] 示例注释使用目标语言
---
## 注释格式检查
### 语言特定格式
- [ ] 符合语言特定的注释风格（JSDoc、Rustdoc 等）
- [ ] 标签使用正确（@param、@returns 等）
- [ ] 标签顺序合理
### 双语格式
- [ ] 所有注释都是中英双语
- [ ] 英文描述在前，中文描述在后
- [ ] 中英文之间有空行分隔
- [ ] 参数描述使用斜杠分隔（`/`）
### 换行格式
- [ ] 注释文本在100字符左右换行
- [ ] 列表项缩进一致
- [ ] 代码块缩进正确
### 标点符号
- [ ] 中文内容使用中文标点
- [ ] 英文内容使用英文标点
- [ ] 引号使用正确
- [ ] 无多余空格
---
## 代码完整性检查
**这是最关键的检查项**，确保注释添加过程中没有意外修改代码：
### 代码逻辑
- [ ] 未修改任何代码逻辑
- [ ] 未添加新代码逻辑
- [ ] 未删除代码逻辑
### 标识符
- [ ] 未修改任何变量名
- [ ] 未修改任何函数名
- [ ] 未修改任何类名
- [ ] 未修改任何属性名
### 代码结构
- [ ] 未添加新代码行
- [ ] 未删除代码行
- [ ] 未重排代码行
- [ ] 未修改代码顺序
### 代码格式
- [ ] 未修改缩进
- [ ] 未修改换行
- [ ] 未修改空格
- [ ] 原有代码格式完全保留
---
## 特殊场景检查
### 复杂条件分支
如果为复杂条件添加了单行注释：
- [ ] 注释清晰解释条件逻辑
- [ ] 注释说明为什么需要这个条件
### 复杂循环
如果为复杂循环添加了单行注释：
- [ ] 注释清晰解释循环目的
- [ ] 注释说明边界条件
### 复杂表达式
如果为复杂表达式添加了单行注释：
- [ ] 注释清晰解释表达式含义
- [ ] 注释说明计算逻辑
---
## 验证流程
### 1. 完整性验证
逐项检查上述完整性检查清单。
### 2. 内容审查
快速浏览注释内容，确保：
- 功能描述准确
- 参数说明完整
- 示例代码可运行
### 3. 格式验证
检查所有注释是否符合格式要求：
- 双语格式
- 换行规则
- 标点符号
### 4. 代码对比
将修改后的文件与原文件对比，确保：
- 只有注释被添加或修改
- 所有代码逻辑完全一致
### 5. 测试验证（如可能）
如果项目有测试，运行测试确保代码功能未受影响。
---
## 常见问题
### 问题：注释与代码不一致
**原因**：代码在添加注释后被修改
**解决**：回退代码修改，只保留注释
### 问题：过多不必要的注释
**原因**：为简单代码添加了注释
**解决**：删除明显多余的注释
### 问题：双语格式不统一
**原因**：部分注释遗漏中文或英文
**解决**：补全所有双语注释
### 问题：示例代码无法运行
**原因**：示例与实际函数签名不符
**解决**：修正示例代码或函数签名

186
.agents/skills/code-commentator/references/writing-style.md Normal file
View File

@@ -0,0 +1,186 @@
# 注释写作风格指南
本指南规范注释的写作风格和语言规范，确保注释专业且一致。
## 目录
- [语气标准](#语气标准)
- [语言与语法规范](#语言与语法规范)
- [示例改进](#示例改进)
---
## 语气标准
### 视角与时态
- **称呼**：以"您"称呼读者
- **语态**：使用主动语态
- **时态**：使用现在时（例如"函数返回..."而非"函数将返回..."）
### 语气要求
- **专业**：避免口语化和非正式表达
- **友好**：保持帮助性的语气，但不冗长
- **直接**：开门见山，避免绕圈子
### 清晰度要求
- **词汇**：使用简单词汇，避免过度使用专业术语
- **俚语**：避免俚语和口语表达
- **营销用语**：避免宣传性和夸张性语言
### 要求层级
明确区分不同层级的指令：
| 层级 | 用词 | 说明 |
| -------- | ------------------ | ------------------------------ |
| 强制要求 | **必须**、**严禁** | 必须遵守的规则，违反会导致错误 |
| 强烈建议 | **推荐**、**建议** | 推荐的最佳实践 |
| 可选建议 | **可以**、**考虑** | 可根据情况选择的建议 |
**避免使用**："应当"、"宜"等模糊表述。
### 措辞选择
| 避免 | 推荐 |
| -------- | -------- |
| 请 | （省略） |
| 允许你 | 可以 |
| 允许您 | 您可以 |
| 函数认为 | 函数检查 |
| 数组包含 | 数组有 |
**可以使用缩写**：不要、它是、它有、它会等。
---
## 语言与语法规范
### 缩写使用
| 避免 | 推荐 |
| ------ | --------- |
| e.g. | 例如 |
| i.e. | 即 |
| etc. | 等 |
| vs. | 与...对比 |
| et al. | 等人 |
### 标点符号
- **序列逗号**：在列表中使用逗号分隔（如"a、b、c"）
- **中文引号**：使用 `""` 而非 `""`
- **英文引号**：使用 `""` 而非 ''
### 日期格式
使用明确格式，例如：
- ✅ "2026年1月22日"
- ✅ "January 22, 2026"
- ❌ "2026/1/22"
- ❌ "1/22/26"
### 简洁性
| 避免 | 推荐 |
| ---------------- | ---- |
| 允许你/您 | 可以 |
| 让我们来看 | 看 |
| 接下来我们将 | 我们 |
| 这个函数的作用是 | 函数 |
### 动词选择
使用精确、具体的动词：
| 模糊动词 | 精确动词 |
| -------- | ---------------------- |
| 处理 | 解析、转换、计算、验证 |
| 获取 | 读取、拉取、提取、请求 |
| 设置 | 配置、赋值、初始化 |
---
## 示例改进
### 改进前（不推荐）
```typescript
/**
* 这个函数可以帮助我们对用户输入的数据进行处理。
* 它会返回一个处理后的结果。
*
* @param input - 输入的数据
* @returns 返回处理后的结果
*/
function processData(input: any) {}
/**
* 这个类是用来管理用户的。
* 它可以帮助我们进行用户认证。
*/
class UserManager {}
```
### 改进后（推荐）
```typescript
/**
* Processes user input data.
*
* 处理用户输入数据。
*
* @param input - User input data to process / 要处理的用户输入数据
* @returns Processed result / 处理后的结果
*/
function processData(input: Data): Result {}
/**
* Manages user authentication and session handling.
*
* 管理用户认证和会话处理。
*
* @example
* const manager = new UserManager();
* const session = await manager.login('user@example.com', 'password');
*/
class UserManager {}
```
### 关键改进点
1. **直接描述功能**：开头直接说明函数/类的功能，而非"这个函数是..."
2. **使用动词开头**：函数描述以动词开头（如 Process、Calculate、Validate）
3. **避免冗余**：删除"可以帮助我们"、"这个"等冗余表述
4. **保持简洁**：每行控制在合理长度内
---
## 注释原则
### 不要过度注释
注释是为了增强可读性，而非为注释而注释。过多注释反而会影响代码可读性。
**添加注释前，先问自己**：
1. 不看注释，能否快速理解这段代码的意图？
2. 代码命名是否足够清晰？
3. 注释是否提供了代码本身无法表达的信息？
如果以上问题的答案表明代码已足够清晰，则不需要添加注释。
### 简洁明了
- 避免冗余注释
- 注释应有实际价值
- 提供代码本身无法表达的信息
### 示例要求
- 所有使用示例必须是可以实际运行的代码
- 示例中使用有意义的名称
- 避免使用"foo"、"bar"等无意义占位符