tools-show/.agents/skills/code-commentator/references/comment-formats.md

注释格式参考指南

本文档提供各种编程语言的注释格式详细示例，供在添加注释时参考。

目录

• 编程语言识别
• 多行注释格式
• 单行注释格式
• 注释文本格式

---

编程语言识别

根据文件扩展名识别编程语言，选择对应的注释风格：

语言	文件扩展名	多行注释风格	单行注释风格
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 格式

/**
 * 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 格式

"""
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 格式

/**
 * 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 格式

// 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 格式

/// 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 格式

/**
 * 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 格式

=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 格式

/// 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 格式

/**
 * 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
}

---

单行注释格式

短描述格式

// english description / 中文描述
if (condition) {
}

// english description / 中文描述
const variable = value;

长描述格式

// This is a longer english description that explains
// the purpose of the following code block.
//
// 这是较长的中文描述，解释以下代码块的用途。
if (complexCondition) {
  // english description / 中文描述
  doSomething();
}

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)

---

特殊注释场景

联合类型参数处理

当参数类型为联合类型时，使用无序列表详细说明每个类型：

/**
 * 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 {}

支持多种传参方式的函数

对于支持多种传参类型或传参个数的函数，需提供不同场景的使用示例：

/**
 * 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个字符左右处换行（长链接或表格等特殊内容除外）：

/**
 * This is a very long description that needs to be wrapped at approximately
 * 100 characters to maintain readability and consistency across the codebase.
 *
 * 这是一个很长的描述，需要在约100个字符处换行，以保持代码库的可读性和一致性。
 */

中英文分隔

双语注释中，英文描述在前，中文描述在后，中间用空行分隔：

/**
 * English description comes first.
 *
 * 中文描述紧随其后。
 */

参数描述格式

参数描述使用斜杠分隔中英文：

@param paramName - English description / 中文描述