阿里Java编程规约（注释）提炼

灰太狼 2023-06-08 03:06 30阅读 0赞

**【强制】类、类属性、类方法的注释必须使用 Javadoc 规范，使用/\*\*内容\*/格式，不得使用**

**// xxx 方式。**

说明：在 IDE 编辑窗口中，Javadoc 方式会提示相关注释，生成 Javadoc 可以正确输出相应注释；在 IDE

中，工程调用方法时，不进入方法即可悬浮提示方法、参数、返回值的意义，提高阅读效率。

**【强制】所有的抽象方法（包括接口中的方法）必须要用 Javadoc 注释、除了返回值、参数、**

**异常说明外，还必须指出该方法做什么事情，实现什么功能。**

说明：对子类的实现要求，或者调用注意事项，请一并说明。

**【强制】所有的类都必须添加创建者和创建日期。**

**【强制】方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释**

**使用/\* \*/注释，注意与代码对齐。**

**【强制】所有的枚举类型字段必须要有注释，说明每个数据项的用途。**

**【推荐】与其“半吊子”英文来注释，不如用中文注释把问题说清楚。专有名词与关键字保**

**持英文原文即可。**

反例：“TCP 连接超时”解释成“传输控制协议连接超时”，理解反而费脑筋。

**【推荐】代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻**

**辑等的修改。**

说明：代码与注释更新不同步，就像路网与导航软件更新不同步一样，如果导航软件严重滞后，就失去了

导航的意义。

**【参考】谨慎注释掉代码。在上方详细说明，而不是简单地注释掉。如果无用，则删除。**

说明：代码被注释掉有两种可能性：1）后续会恢复此段代码逻辑。2）永久不用。前者如果没有备注信

息，难以知晓注释动机。后者建议直接删掉（代码仓库已然保存了历史代码）。

**【参考】对于注释的要求：第一、能够准确反映设计思想和代码逻辑；第二、能够描述业务**

**含义，使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者**

**形同天书，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路；注释也是给继**

**任者看的，使其能够快速接替自己的工作。**

**【参考】好的命名、代码结构是自解释的，注释力求精简准确、表达到位。避免出现注释的**

**一个极端：过多过滥的注释，代码的逻辑一旦修改，修改注释是相当大的负担。**

反例：

// put elephant into fridge

put(elephant, fridge);

方法名 put，加上两个有意义的变量名 elephant 和 fridge，已经说明了这是在干什么，语义清晰的代

码不需要额外的注释。

发表评论取消回复

表情：

评论列表（有 0 条评论，30人围观）

还没有评论，来说两句吧...

相关阅读

相关阿里Java编程规约（注释）提炼

【强制】类、类属性、类方法的注释必须使用 Javadoc 规范，使用/\\内容\/格式，不得使用 // xxx 方式。说明：在 IDE 编辑窗口中，Javadoc 方式会

灰太狼/ 2023年06月08日 03:06/ 0 赞/ 31 阅读

相关阿里开源共享：IDE导入阿里编码规约格式化模板和注释模板

文章目录 [向IDE导入阿里编码规约格式化模板和注释模板][IDE] [向eclipse导入][eclipse]

忘是亡心i/ 2023年03月03日 08:52/ 0 赞/ 23 阅读

相关阿里代码规约（泰山版）- 索引规约

1. 【强制】业务上具有唯一特性的字段，即使是组合字段，也必须建成唯一索引。说明：不要以为唯一索引影响了 insert 速度，这个速度损耗可以忽略，但提高查找速

怼烎@/ 2022年12月31日 12:27/ 0 赞/ 210 阅读

相关 alibaba 注释规约模板

注释配置 ![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nL

心已赠人/ 2022年12月20日 02:11/ 0 赞/ 77 阅读

相关阿里Java开发手册之编程规约

阿里Java开发手册之编程规约对于程序员来说，编程规范可以养成良好的编程习惯，提高代码质量，降低沟通成本。就在2月9号，阿里出了一份Java开发手册(正式版)，分为编程

浅浅的花香味﹌/ 2022年07月12日 04:22/ 0 赞/ 246 阅读

相关白话阿里巴巴Java开发手册（编程规约）

原文地址：http://geek.csdn.net/news/detail/193124 最近，阿里巴巴发布了《阿里巴巴Java开发手册》，总结了阿里人多年一线实战中积累的研

桃扇骨/ 2022年06月17日 06:39/ 0 赞/ 330 阅读

相关阿里巴巴Java开发手册-编程规约

本文转自：[http://www.jianshu.com/p/bc8fed863eca?hmsr=toutiao.io&utm\_medium=toutiao.io&u

末蓝、/ 2022年06月17日 05:29/ 0 赞/ 642 阅读

相关阿里java编码规范（三）控制语句，注释规约

最近阿里出了一个java开发手册，里面涉及到很多工作规范的地方，有很多借鉴和参考的作用，也可以给新入行的工程师作为参考。下载地址是在：http://techforum-im

蔚落/ 2022年06月14日 07:51/ 0 赞/ 227 阅读

相关 java编程规约

整理于 [阿里巴巴Java开发手册][Java] 一、编程规约 (一) 命名风格 > > 1. 【强制】代码中的命名均不能以下划线或美元符号开始，

不念不忘少年蓝@/ 2022年05月09日 00:34/ 0 赞/ 364 阅读

相关 Java开发手册之注释规约

1. 【强制】类、类属性、类方法的注释必须使用Javadoc规范，使用`/内容/`格式，不得使用 // xxx方式。说明：在IDE编辑窗口中，Jav

﹏ヽ暗。殇╰゛Y/ 2021年12月10日 01:19/ 0 赞/ 352 阅读