---
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）
```