cat-shark/lpt-be

Fork 0

Files

T

cat-shark a92465dfc0 chore: 清理冗余注释，保留字段/业务含义注释

2026-05-27 23:03:43 +08:00

4.7 KiB

Raw Permalink Blame History

name, description, metadata

name

description

metadata

comment-cleanup

提交代码前优化 Java 注释，移除冗余描述性注释，保留功能性注释和业务上下文注释。

short-description
清理 Java 代码中的冗余注释

Comment Cleanup

在代码提交前，扫描变更的 Java 文件，清理冗余注释，保留有价值的注释。

触发条件

用户要求清理注释、优化注释、提交前检查注释时使用。

工作流程

定位待清理的 Java 文件（通常是 git diff 中变更的文件）
逐文件扫描注释，按规则分类处理
执行清理（删除或改造）
输出清理报告

注释分类规则

移除：类型 A — 代码语义重复注释

代码本身已经清晰表达意图时，删除多余的行内注释。

// ❌ 移除：代码已经说清楚了
// 转换报告
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 的"框架机制"章节集中描述。代码中的此类注释一律移除。

// ❌ 移除：框架机制已在 AGENTS.md 中说明
// created_by 条件由 TenantLineInnerInterceptor 自动注入
List<StudyReportsEntity> reports = studyReportsMapper.selectList(...)

// ❌ 移除
// 拦截器自动校验归属
return Optional.ofNullable(studyReportsMapper.selectById(id)) ...

// ❌ 移除
// created_by 由 MetaObjectHandler 自动填充
studySessionsServiceImpl.save(...)

移除：类型 D — 空注释 / 无信息量注释

// ❌ 空 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： 保留，说明字段的业务含义。

// ✅ 保留：字段含义对理解数据模型有帮助
/**
 * 账号-登录用
 */
@TableField(value = "user_name")
private String userName;

类 Javadoc： 保留，但只描述类的职能，不包含实现技术细节。

// ❌ 移除：实现技术属于实现细节，不属于类描述
/** 复习模块 Service 实现（纯 MyBatis-Plus Java API） */

// ✅ 保留：只描述职能
/** 复习模块 Service 实现 */

改造：类型 E — 枚举注释

枚举中的中文含义注释应迁移到枚举类的专用字段中，而非用注释标注。

// ❌ 改造前：用注释标注含义
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 等字段，则直接删除注释。

常量注释保留不变：

// ✅ 常量注释保留
// 最大重试次数
private static final int MAX_RETRY = 3;

保留：类型 F — TODO / FIXME 注释

// ✅ 保留
//todo 参数传递未加密

执行命令

# 获取变更的 Java 文件
git diff --cached --name-only --diff-filter=ACMR -- '*.java'

# 对每个文件逐行扫描，按上述规则处理

输出格式

清理完成后，输出简要报告：

✅ 清理完成，共处理 N 个文件：
  - 移除冗余注释 X 处
  - 改造枚举注释 Y 处（需人工确认新增字段）
  - 保留注释 Z 处（字段Javadoc/TODO）

4.7 KiB Raw Permalink Blame History Unescape Escape