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

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"等无意义占位符