Alibaba Java Coding Guidelines 注释规约深度解析从 11 条强制规范到 p3c-pmd 规则实现【免费下载链接】p3cAlibaba Java Coding Guidelines pmd implements and IDE plugin项目地址: https://gitcode.com/gh_mirrors/p3/p3c导读注释是代码可读性的第一道防线也是团队协作中信息传递成本最低的载体。《阿里巴巴 Java 开发手册黄山版》将注释规范单独成章以【强制】【推荐】【参考】三个等级定义了从 Javadoc 格式、作者信息、枚举注释到 TODO/FIXME 标记的完整注释体系。本文以仓库中的 注释规约 文档为主体结合 p3cAlibaba Java Coding Guidelines 的 PMD 实现与 IDE 插件中 comment 规则包 的源码与 注释规则测试逐条拆解每条规约的含义、为什么这样规定以及工具链如何把纸面规范变成可以自动拦截的检查项。读完本文你将既能写出符合规范的注释也能理解 p3c-pmd 背后基于 AST 的静态检查原理。一、规范总览三档级别与六条可自动化的规则《阿里巴巴 Java 开发手册》对每条规约都标注了强制程度【强制】必须遵守违反即产生告警是代码评审的硬性门槛【推荐】应当遵守属于最佳实践多数场景下应优先满足【参考】提供背景知识与建议供团队按需采纳。在 注释规约 的 11 条中前 5 条为【强制】第 6、7 条为【推荐】第 811 条为【参考】。p3c-pmd 将其中 6 条固化为可执行的 PMD 规则通过 CommentRulesTest.java 中的java-ali-comment规则集注册对应关系如下规约条目强制程度对应 PMD 规则实现第 1 条Javadoc 格式强制CommentsMustBeJavadocFormatRule第 2 条抽象方法 Javadoc强制AbstractMethodOrInterfaceMethodMustUseJavadocRule第 3 条类必须有创建者与日期强制ClassMustHaveAuthorRule第 4 条方法内注释位置强制AvoidCommentBehindStatementRule第 5 条枚举字段必须有注释强制EnumConstantsMustHaveCommentRule第 8 条谨慎注释掉代码参考RemoveCommentedCodeRule其余第 6、7、9、10、11 条属于主观判断较强的实践建议工具难以无歧义判定主要依赖人工评审下文将逐一展开。二、【强制】类、类属性、类方法的注释必须使用 Javadoc 规范规约原文类、类属性、类方法的注释必须使用 Javadoc 规范使用/**内容*/格式不得使用// xxx方式。为什么强制Javadoc 注释不只是给人看的更是给工具看的。使用/** */格式后IDE 编辑窗口中会以特殊样式提示该注释执行javadoc命令可以正确生成 API 文档在 IDE 中调用方法时鼠标悬浮即可不进入方法体看到方法、参数、返回值的意义极大提高阅读效率。源码实现PMD 将 Java 注释分为FormalCommentJavadoc、MultiLineComment/* */和SingleLineComment//三类。在 CommentsMustBeJavadocFormatRule.java 中规则分别覆写visit方法处理类声明ASTClassOrInterfaceDeclaration、构造器ASTConstructorDeclaration、方法ASTMethodDeclaration、字段ASTFieldDeclaration与枚举ASTEnumDeclaration核心检查逻辑为private void checkComment(AbstractJavaAccessNode decl, Object data, MessageMaker maker) { Comment comment decl.comment(); if (comment instanceof SingleLineComment || comment instanceof MultiLineComment) { addViolationWithMessage(data, decl, maker.make(), comment.getBeginLine(), comment.getEndLine()); } }也就是说只要声明前面的注释是//或/* */而非/** */就立刻报告违规。以类为例检查类声明时会对类名给出提示检查构造器时若构造器带参数还会把参数列表拼进告警信息源码中通过decl.getFormalParameters()遍历ASTFormalParameter生成方便开发者一眼定位是哪个构造器缺注释。值得注意的边界处理该规则在检查前会调用assignCommentsToDeclarations(cUnit)做一次注释归属匹配——只有紧邻声明上一行的注释才被认为是该声明的注释其中注释与声明之间只允许存在注解ASTAnnotation如Override匿名内部类内的注释会被跳过与声明同行、位于声明之后的注释不会被误判为声明注释。反例与正例// 错误使用 // 给类注释 public class OrderService { // 错误使用 // 给字段注释 private Long orderId; } /** 正确类的 Javadoc 注释 */ public class OrderService { /** 正确字段的 Javadoc 注释 */ private Long orderId; }三、【强制】抽象方法与接口方法必须使用 Javadoc且要素完整规约原文所有的抽象方法包括接口中的方法必须要用 Javadoc 注释除了返回值、参数、异常说明外还必须指出该方法做什么事情实现什么功能。对子类的实现要求或者调用注意事项请一并说明。为什么强制抽象方法和接口方法没有方法体调用者唯一的信息来源就是注释。如果注释只写了参数和返回值却不说明方法职责调用者依然无法理解方法语义若缺少param、return、throws中的任何一项IDE 悬浮提示和生成的 Javadoc 都不完整。源码实现AbstractMethodOrInterfaceMethodMustUseJavadocRule.java 的检查逻辑非常精细它验证 Javadoc 的四个维度方法职责描述用正则[/*\n\r\s](.*)?匹配注释内容若注释除去格式符号后为空即只有/** */空壳、没有方法说明文字报告.desc违规参数说明通过 XPath./MethodDeclarator/FormalParameters/FormalParameter/VariableDeclaratorId取出全部形参名再逐一用.*param\s形参名.*正则确认 Javadoc 中存在对应param标签返回值说明若方法非 void则要求注释中出现return异常说明若方法声明了throws异常列表则要求注释中出现对应的throws标签。对于抽象类的抽象方法源码通过decl.isAbstract()判定后遍历所有抽象方法检查对于接口方法则通过 XPath./ClassOrInterfaceBody/ClassOrInterfaceBodyDeclaration/MethodDeclaration定位对应METHOD_IN_INTERFACE_XPATH常量。规范示例/** * 根据订单号查询订单并校验订单是否属于当前用户。 * * param orderId 订单号不允许为空 * param userId 用户 ID用于归属校验 * return 订单实体未找到时返回 null * throws IllegalArgumentException orderId 或 userId 为空时抛出 */ Order getOrder(Long orderId, Long userId);注意该规则要求方法做什么事情必须写清楚这与第 10 条注释力求精简准确并不矛盾——说明职责 ≠ 逐行解释实现。四、【强制】所有类必须添加创建者和创建日期规约原文所有的类都必须添加创建者和创建日期。这是规范中信息量最少、但对工程追溯最有价值的一条知道这个类是谁在什么时候建的后续的疑问可以直接找到第一责任人。源码实现ClassMustHaveAuthorRule.java 用正则.*[Aa]uthor.*忽略大小写、DOTALL 模式在类注释中查找author标记。它的检查对象覆盖类、接口、枚举ASTEnumDeclaration与注解类型ASTAnnotationTypeDeclaration并有两条精心设计的边界规则只检查 public 类型一个编译单元内如果有多个类定义只检查 public 的那个源码注释明确说明If a CompilationUnit has multi class definition, only the public one will be checked内部枚举不单独检查若枚举有外层类父节点是ASTClassOrInterfaceDeclaration则认为其作者信息由外层类注释承载直接跳过。当类完全没有注释时报告缺少注释违规有注释但缺少author时报告缺少作者违规。规范示例/** * 订单领域服务 * * author zhang.san * date 2024-06-01 */ public class OrderDomainService { }五、【强制】方法内部注释单行注释在语句上方另起一行多行注释注意对齐规约原文方法内部单行注释在被注释语句上方另起一行使用//注释。方法内部多行注释使用/* */注释注意与代码对齐。为什么强制行尾注释trailing comment与代码挤在同一行会破坏行宽统一、导致注释与代码难以区分也不利于 diff 时精确定位而另起一行 对齐让注释和它解释的语句形成清晰的上下级关系。源码实现AvoidCommentBehindStatementRule.java 通过按行号排序的SortedMap同时收录表达式ASTExpression、字段声明ASTFieldDeclaration、枚举常量ASTEnumConstant与注释节点然后判断注释与它前面最近节点的位置关系if (lastNode ! null (comment.getBeginLine() lastNode.getBeginLine()) (comment.getEndColumn() lastNode.getBeginColumn())) { addViolationWithMessage(...); // 注释与语句同处一行且位于语句之后 }即只要注释的起始行与前一语句的起始行相同、且注释起始列在语句起始列之后就判定为语句后面的行尾注释并报告违规。正反例// 正确注释在语句上方另起一行 // 校验订单状态 checkOrderStatus(order); boolean ok checkOrderStatus(order); // 错误行尾注释六、【强制】所有枚举类型字段必须有注释规约原文所有的枚举类型字段必须要有注释说明每个数据项的用途。枚举常量没有注释时PAYED、CANCELED这类短命名在业务语境中极易产生歧义——PAYED是已支付还是待支付一个常量一条注释用一句话说明用途即可。源码实现EnumConstantsMustHaveCommentRule.java 的思路是把枚举声明ASTEnumDeclaration与枚举常量ASTEnumConstant按行号排序后如果枚举声明之后紧跟的第一个非注释节点是枚举常量即枚举体的第一个常量前没有任何注释就报告违规。规范示例public enum OrderStatus { /** 已创建等待支付 */ CREATED, /** 已支付等待发货 */ PAID, /** 已取消 */ CANCELED }七、【推荐】注释语言选择与代码同步更新第 6 条推荐与其用半吊子英文注释不如用中文把问题说清楚专有名词与关键字保持英文原文即可。手册给出的反例是把TCP 连接超时解释成传输控制协议连接超时反而增加了阅读负担。这条背后的原则是注释的首要目标是准确传递信息其次才是格式优雅——术语该保留原文就保留原文如TCP、REST、HashMap描述性文字用团队最熟悉的语言。第 7 条推荐代码修改的同时注释也要同步修改尤其是参数、返回值、异常、核心逻辑的修改。手册用了一个贴切的比喻代码与注释更新不同步就像路网与导航软件更新不同步导航严重滞后就失去了导航的意义。这条在实践中最常见的问题是重构改了方法签名却忘了改param恰好第 3 条中的param/return/throws完整性检查能在一定程度上兜底——参数名变了而注释没跟上规则会因正则匹配失败而报告违规等于工具帮人盯着注释同步。八、【参考】谨慎注释掉代码与注释质量的三条原则第 8 条参考谨慎注释掉代码。手册要求如果需要保留被注释的代码必须在上方详细说明原因而不是简单注释掉如果确认无用则直接删除。原因很清晰被注释的代码只有两种宿命——后续会恢复或永久不用。前者若无备注后人不知道注释动机后者留着只会污染代码而代码仓库如 Git本身就保存着历史版本删掉并不丢失。源码实现这条虽然标为【参考】p3c-pmd 仍然提供了 RemoveCommentedCodeRule.java 来自动识别被注释掉的代码。它的识别引擎按顺序扫描注释内容用正则匹配四类典型代码模式源码中定义在CommentPatternEnum被注释的 import.*import\s(static\s)?(\w*\.)*\w*;.*被注释的字段.*private\s(\w*)\s(\w*);.*被注释的方法.*(public|protected|private)\s\w\s\w\(.*\)\s\{.*被注释的语句.*\.\w\(.*\);\n.*形如xxx.yyy(...);的调用语句规则同样做了边界处理包含pre标签的注释典型是 Javadoc 中的代码示例会被跳过PRE_TAG_PATTERN整行以///开头的注释视为主动屏蔽SUPPRESS_PATTERN不触发告警语句模式只在方法体内ASTBlockStatement判定有效避免把类声明前的注释误报。第 9 条参考对注释的要求有两点——第一能够准确反映设计思想和代码逻辑第二能够描述业务含义让其他程序员迅速了解代码背后的信息。完全没有注释的大段代码对阅读者形同天书注释是给自己看的隔很长时间也能清晰理解当时的思路注释也是给继任者看的使其能快速接替工作。第 10 条参考好的命名、代码结构是自解释的注释力求精简准确、表达到位避免走向过多过滥的另一个极端——代码逻辑一旦修改维护大量注释是相当大的负担。手册给出的反例是// put elephant into fridge put(elephant, fridge);方法名put加上两个有意义的变量名elephant和fridge已经说明了这是在干什么语义清晰的代码不需要额外注释。这条与第 8 条、第 2 条共同勾勒出注释的平衡点接口处类、抽象方法要详细实现处要精简能靠命名表达的不写注释写了注释就要与代码同步。九、【参考】TODO 与 FIXME 特殊标记规范规约原文特殊注释标记请注明标记人与标记时间。注意及时处理这些标记通过标记扫描经常清理。线上故障有时候就来源于这些标记处的代码。两种标准标记的格式与语义标记格式语义TODOTODO标记人标记时间[预计处理时间]表示需要实现、但目前还未实现的功能。本质是一个 Javadoc 标签虽然当前 Javadoc 工具尚未正式支持但已被广泛使用只能应用于类、接口和方法因为它是 Javadoc 标签FIXMEFIXME标记人标记时间[预计处理时间]在注释中用 FIXME 标记某段代码是错误的、不能工作的需要及时纠正实践建议/** * 支持批量导入后的异步对账。 * TODO (zhang.san, 2024-06-01, 2024-06-15) */ public void asyncReconcile() { } // FIXME (li.si, 2024-06-10)下方算法在极端并发下可能丢失计数需替换为原子实现无论 IDE 的 TODO 面板还是grep -rn TODO\|FIXME扫描规范的标记人 标记时间 预计处理时间三要素都是后续排期与追责的基础而及时清理则是防止这些标记成为永久地雷的关键——手册特别提醒线上故障有时候就来源于这些标记处的代码。十、规则如何落地p3c 的工程化路径p3c 将上述注释规约固化为 PMD 规则后可以通过三条途径应用到日常开发命令行 / CI 集成p3c-pmd 模块pom.xml打包后可作为 PMD 规则集运行接入 CI 流水线在代码合入前自动扫描注释类违规IntelliJ IDEA 插件仓库 idea-plugin 模块将 PMD 检查封装为 IDE 的 Inspection编码过程中实时高亮注释违规并支持快速修复如 ClassMustHaveAuthorQuickFix 会自动为缺失作者信息的类补全模板相关检查入口见 AliInspectionAction.ktEclipse 插件仓库 eclipse-plugin 模块提供同等能力的 Eclipse 插件PMD 规则的 Java 版实现与 IDE 无关可直接复用。验证方面CommentRulesTest.java 基于 PMD 官方测试框架SimpleAggregatorTst一次性注册了java-ali-comment规则集中的全部 6 条注释规则配套的测试数据正例与反例代码片段保证了每条规则的行为可回归、可预期。结语注释规约的 11 条规范本质是在回答三个问题注释写在哪Javadoc 接口注释、方法内上方注释、注释写什么职责、作者、参数、返回、异常、TODO/FIXME 三要素、注释不写什么行尾注释、被注释掉的死代码、过度解释。p3c-pmd 用 6 条可执行的 PMD 规则 1 套自动化测试把其中最可判定的部分变成了机器检查而语言选择、同步更新、精简表达到位这类需要判断力的规范仍依赖每个开发者的代码评审自觉。把工具规则与人工评审结合才能让注释真正成为代码的导航软件而不是路障。【免费下载链接】p3cAlibaba Java Coding Guidelines pmd implements and IDE plugin项目地址: https://gitcode.com/gh_mirrors/p3/p3c创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考