---
name: yangge521/code-comment-cn
source: https://app.decimal.ai/s/yangge521-code-comment-cn@1/SKILL.md
source_sha256: dfd5a597435b
---

# 中文代码注释规范

## 概述

提供多语言代码注释规范，确保代码可读性和可维护性。支持 Python（docstring）、JavaScript（JSDoc）、Go、Java 等语言。

## 使用场景

- 新项目启动：建立代码注释规范
- 代码审查：检查注释完整性
- 老项目重构：补充缺失注释
- API 开发：函数/类接口注释
- GPU 推理代码：复杂逻辑注释
- 团队协作：统一注释风格

## 注释规范

### Python（Google 风格 docstring）

函数注释包含：功能描述、Args（参数名/类型/说明）、Returns（返回值类型/说明）、Raises（异常）、Example（示例）。

### JavaScript（JSDoc）

使用 @param/@returns/@throws 标签，支持类型推断。

### 通用规则

- 文件头注释：文件功能、作者、创建日期
- 类注释：类的职责和使用方式
- 复杂逻辑：解释"为什么"而非"做什么"
- TODO/FIXME：标注待办和已知问题
- 中文注释，技术术语保留英文

## 常见问题与排查

| 问题 | 原因 | 解决方案 |
|------|------|---------|
| 注释与代码不一致 | 修改代码未更新注释 | CI 检查注释同步 |
| 过度注释 | 注释显而易见的代码 | 只注释复杂逻辑 |
| 注释风格不统一 | 无规范约束 | 使用 lint 工具检查 |
| 缺少参数说明 | 偷懒省略 | CI 强制 docstring |

## 扩展方向

- **AI 自动注释**: 使用 AI 自动生成注释初稿
- **文档生成**: 从 docstring 自动生成 API 文档
- **注释覆盖率**: 工具统计注释覆盖率
- **多语言支持**: 扩展到 Rust/Swift/Kotlin
- **注释模板**: 按场景维护注释模板
- **国际化**: 中英双语注释

## 技能链路

- **code-review-cn**: 代码审查检查注释完整性
- **readme-generator**: 从注释提取信息生成 README
- **tech-doc-cn**: 从注释生成技术文档
- **git-workflow**: 提交前检查注释规范

## 检查清单

- [ ] 所有公共函数有 docstring
- [ ] 参数和返回值已标注类型
- [ ] 复杂逻辑有注释说明
- [ ] TODO 标注负责人和日期
- [ ] 注释语言统一为中文