179 lines
4.7 KiB
Markdown
179 lines
4.7 KiB
Markdown
---
|
||
name: comment-cleanup
|
||
description: 提交代码前优化 Java 注释，移除冗余描述性注释，保留功能性注释和业务上下文注释。
|
||
metadata:
|
||
short-description: 清理 Java 代码中的冗余注释
|
||
---
|
||
|
||
# Comment Cleanup
|
||
|
||
在代码提交前，扫描变更的 Java 文件，清理冗余注释，保留有价值的注释。
|
||
|
||
## 触发条件
|
||
|
||
用户要求清理注释、优化注释、提交前检查注释时使用。
|
||
|
||
## 工作流程
|
||
|
||
1. 定位待清理的 Java 文件（通常是 `git diff` 中变更的文件）
|
||
2. 逐文件扫描注释，按规则分类处理
|
||
3. 执行清理（删除或改造）
|
||
4. 输出清理报告
|
||
|
||
## 注释分类规则
|
||
|
||
### 移除：类型 A — 代码语义重复注释
|
||
|
||
代码本身已经清晰表达意图时，删除多余的行内注释。
|
||
|
||
```java
|
||
// ❌ 移除：代码已经说清楚了
|
||
// 转换报告
|
||
List<ReviewFeedItem> reportItems = reports.stream().map(r -> toFeedItem(r)).collect(Collectors.toList());
|
||
|
||
// ❌ 移除：合并逻辑一眼就能看出
|
||
// 合并并按创建时间倒序
|
||
return Stream.concat(reportItems.stream(), fragmentItems.stream())
|
||
.sorted(Comparator.comparing(ReviewFeedItem::getCreatedTime).reversed())
|
||
.collect(Collectors.toList());
|
||
|
||
// ❌ 移除：查询目的从变量名已可知
|
||
// 先查该任务下的所有 sessionNum
|
||
List<String> sessionNums = studySessionsMapper.selectList(...)
|
||
```
|
||
|
||
**判断标准：** 如果删掉注释后，一个熟悉 Java/Spring 的开发者看代码没有任何困惑，就该移除。
|
||
|
||
**例外：** 方法级的 Javadoc（`/** ... */`）即使与代码重复，也保留，因为它服务于 IDE 提示和文档生成。
|
||
|
||
### 移除：类型 B — 框架机制注释
|
||
|
||
框架隐式行为（拦截器、MetaObjectHandler、AOP 等）的说明不在代码中重复标注，而是在 `AGENTS.md` 的"框架机制"章节集中描述。代码中的此类注释一律移除。
|
||
|
||
```java
|
||
// ❌ 移除：框架机制已在 AGENTS.md 中说明
|
||
// created_by 条件由 TenantLineInnerInterceptor 自动注入
|
||
List<StudyReportsEntity> reports = studyReportsMapper.selectList(...)
|
||
|
||
// ❌ 移除
|
||
// 拦截器自动校验归属
|
||
return Optional.ofNullable(studyReportsMapper.selectById(id)) ...
|
||
|
||
// ❌ 移除
|
||
// created_by 由 MetaObjectHandler 自动填充
|
||
studySessionsServiceImpl.save(...)
|
||
```
|
||
|
||
### 移除：类型 D — 空注释 / 无信息量注释
|
||
|
||
```java
|
||
// ❌ 空 Javadoc
|
||
/**
|
||
*
|
||
*/
|
||
@TableField(value = "created_time")
|
||
private LocalDateTime createdTime;
|
||
|
||
// ❌ 纯标注作者（无版本/日期等有价值信息时）
|
||
/**
|
||
* @author guo
|
||
*/
|
||
public class GlobalExceptionHandler { ... }
|
||
|
||
// ❌ 重复 HTTP 状态码（CommonResult.error 已隐含 400）
|
||
//code:400
|
||
return CommonResult.error(ex.getMessage());
|
||
```
|
||
|
||
### 保留：类型 C — 字段/类 Javadoc
|
||
|
||
字段 Javadoc 描述数据含义，类 Javadoc 描述模块职能。
|
||
|
||
**字段 Javadoc：** 保留，说明字段的业务含义。
|
||
|
||
```java
|
||
// ✅ 保留：字段含义对理解数据模型有帮助
|
||
/**
|
||
* 账号-登录用
|
||
*/
|
||
@TableField(value = "user_name")
|
||
private String userName;
|
||
```
|
||
|
||
**类 Javadoc：** 保留，但只描述类的职能，不包含实现技术细节。
|
||
|
||
```java
|
||
// ❌ 移除：实现技术属于实现细节，不属于类描述
|
||
/** 复习模块 Service 实现（纯 MyBatis-Plus Java API） */
|
||
|
||
// ✅ 保留：只描述职能
|
||
/** 复习模块 Service 实现 */
|
||
```
|
||
|
||
### 改造：类型 E — 枚举注释
|
||
|
||
枚举中的中文含义注释应迁移到枚举类的专用字段中，而非用注释标注。
|
||
|
||
```java
|
||
// ❌ 改造前：用注释标注含义
|
||
public enum Strategy {
|
||
// 创建组
|
||
CREATE("C"),
|
||
// 更新组
|
||
UPDATE("U");
|
||
}
|
||
|
||
// ✅ 改造后：用字段存储含义
|
||
public enum Strategy {
|
||
CREATE("C", "创建组"),
|
||
UPDATE("U", "更新组");
|
||
|
||
private final String code;
|
||
private final String label;
|
||
|
||
Strategy(String code, String label) {
|
||
this.code = code;
|
||
this.label = label;
|
||
}
|
||
|
||
public String getCode() { return code; }
|
||
public String getLabel() { return label; }
|
||
}
|
||
```
|
||
|
||
如果枚举已有 `label`/`desc` 等字段，则直接删除注释。
|
||
|
||
**常量注释保留不变：**
|
||
```java
|
||
// ✅ 常量注释保留
|
||
// 最大重试次数
|
||
private static final int MAX_RETRY = 3;
|
||
```
|
||
|
||
### 保留：类型 F — TODO / FIXME 注释
|
||
|
||
```java
|
||
// ✅ 保留
|
||
//todo 参数传递未加密
|
||
```
|
||
|
||
## 执行命令
|
||
|
||
```bash
|
||
# 获取变更的 Java 文件
|
||
git diff --cached --name-only --diff-filter=ACMR -- '*.java'
|
||
|
||
# 对每个文件逐行扫描，按上述规则处理
|
||
```
|
||
|
||
## 输出格式
|
||
|
||
清理完成后，输出简要报告：
|
||
|
||
```
|
||
✅ 清理完成，共处理 N 个文件：
|
||
- 移除冗余注释 X 处
|
||
- 改造枚举注释 Y 处（需人工确认新增字段）
|
||
- 保留注释 Z 处（字段Javadoc/TODO）
|
||
```
|