阿里巴巴 Java 开发手册 (八) 注释规约
1. 【强制】类、类属性、类方法的注释必须使用 Javadoc 规范,使用/**内容*/格式,不得使用 //xxx 方式。 说明:在 IDE 编辑窗口中,Javadoc 方式会提示相关注释,生成 Javadoc 可以正确输出相应注 释;在 IDE 中,工程调用方法时,不进入方法即可悬浮提示方法、参数、返回值的意义,提高 阅读效率。
2. 【强制】所有的抽象方法(包括接口中的方法)必须要用 Javadoc 注释、除了返回值、参数、 异常说明外,还必须指出该方法做什么事情,实现什么功能。 说明:对子类的实现要求,或者调用注意事项,请一并说明。
3. 【强制】所有的类都必须添加创建者和创建日期。
4. 【强制】方法内部单行注释,在被注释语句上方另起一行,使用//注释。方法内部多行注释 使用/* */注释,注意与代码对齐。
5. 【强制】所有的枚举类型字段必须要有注释,说明每个数据项的用途。
6. 【推荐】与其“半吊子”英文来注释,不如用中文注释把问题说清楚。专有名词与关键字保持 英文原文即可。 反例:“TCP 连接超时”解释成“传输控制协议连接超时”,理解反而费脑筋。
7. 【推荐】代码修改的同时,注释也要进行相应的修改,尤其是参数、返回值、异常、核心逻辑 等的修改。 说明:代码与注释更新不同步,就像路网与导航软件更新不同步一样,如果导航软件严重滞后, 就失去了导航的意义。
8. 【参考】合理处理注释掉的代码。在上方详细说明,而不是简单的注释掉。如果无用,则删除。 说明:代码被注释掉有两种可能性:1)后续会恢复此段代码逻辑。2)永久不用。前者如果没 有备注信息,难以知晓注释动机。后者建议直接删掉(代码仓库保存了历史代码)。
9. 【参考】对于注释的要求:第一、能够准确反应设计思想和代码逻辑;第二、能够描述业务含 义,使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同
天书,注释是给自己看的,即使隔很长时间,也能清晰理解当时的思路;注释也是给继任者看 的,使其能够快速接替自己的工作。
10. 【参考】好的命名、代码结构是自解释的,注释力求精简准确、表达到位。避免出现注释的 一个极端:过多过滥的注释,代码的逻辑一旦修改,修改注释是相当大的负担。 反例: // put elephant into fridge put(elephant, fridge); 方法名 put,加上两个有意义的变量名 elephant 和 fridge,已经说明了这是在干什么,语 义清晰的代码不需要额外的注释。
11. 【参考】特殊注释标记,请注明标记人与标记时间。注意及时处理这些标记,通过标记扫描, 经常清理此类标记。线上故障有时候就是来源于这些标记处的代码。 1) 待办事宜(TODO):( 标记人,标记时间,[预计处理时间]) 表示需要实现,但目前还未实现的功能。这实际上是一个 Javadoc 的标签,目前的 Javadoc 还没有实现,但已经被广泛使用。只能应用于类,接口和方法(因为它是一个 Javadoc 标签)。
2) 错误,不能工作(FIXME):(标记人,标记时间,[预计处理时间]) 在注释中用 FIXME 标记某代码是错误的,而且不能工作,需要及时纠正的情况。
阿里巴巴 Java 开发手册 (八) 注释规约的更多相关文章
- 阿里巴巴Java开发手册(格式规约篇)——查自己的漏-补自己的缺
(三) 格式规约 1. [强制]大括号的使用约定.如果是大括号内为空,则简洁地写成{}即可,不需要换行:如果是非空代码块则: 1) 左大括号前不换行.行. 2) 左大括号后换行. 3) 右大括号前换行 ...
- 【阿里巴巴Java开发手册1.7.0(嵩山版)】编程规约&MySQL 数据库规约
阿里巴巴Java开发手册1.7.0(嵩山版) 一.编程规约 (一)命名风格 所有命名不得以下划线和$开始和结束. 所有命名不得以拼音或拼音英文混合. 类名使用UpperCamelCase风格. 方法名 ...
- 读阿里巴巴Java开发手册v1.2.0之编程规约有感【架构篇】
不为过去蹉跎,改变当下. 为什么开篇就送这么一句话给大家,我相信很多处于1-3年码龄的哥们儿们,在平时的编码历程中编码的个性可能是多彩的,每个人都有每个人特定的风格,但是我们现在这么随意写,以后这么 ...
- 《阿里巴巴Java开发手册v1.2》解析(编程规约篇)
之前在乐视天天研究各种底层高大上的东西,因为我就一个人,想怎么弄怎么弄.如今来了新美大,好好研读一下<阿里巴巴Java开发手册v1.2>.还要对这么看似简单的东西解析一番.毕竟现在带团队, ...
- 阿里巴巴Java开发手册及Java代码规约扫描eclipse和IDEA插件
<阿里巴巴Java开发手册>: https://github.com/alibaba/p3c/blob/master/%E9%98%BF%E9%87%8C%E5%B7%B4%E5%B7%B ...
- 阿里巴巴Java开发手册———个人追加的见解和补充(一)
先上干货,<阿里巴巴Java开发手册>的下载地址 https://yq.aliyun.com/articles/69327?spm=5176.100239.blogcont69327.15 ...
- 读阿里巴巴Java开发手册v1.2.0之工程结构有感【架构篇】
首先,把昨天那俩条sql语句的优化原因给大家补充一下,第一条效率极低,第二条优化后的,sql语句截图如下: 经过几个高手的评论和个人的分析: 第一条sql语句查询很慢是因为它首先使用了in关键字查询, ...
- 《阿里巴巴 Java 开发手册》读书笔记
偶然看到阿里巴巴居然出书了???趁着满减活动(节约节约....)我赶紧买来准备看看,刚拿到的时候掂量了好多下,总觉得商家给我少发了一本书,结果打开才知道..原来这本书这么小.... 编码规范的重要性 ...
- 码出高效,阿里巴巴JAVA开发手册1.4.0
码出高效,阿里巴巴JAVA开发手册1.4.0阅读笔记 一.编程规约(三) 代码格式// 关键词if与括号之间必须有一个空格,括号内的f与左括号,0与右括号不需要空格 if (flag == 0) { ...
随机推荐
- python 函数注解 参数后面加冒号 函数后面加箭头
由于 python 是动态语言,在定义函数时,参数是不需要指定类型的.当调用别人写的函数,而该函数有没有文档说明,只有通过看源代码才能知道需要传递什么类型的参数. 不过 python 提供了一种机制可 ...
- R语言 rds文件 和 文本文件 转换
library(data.table) ## 读取 rds 文件,然后保存为文本文件 data <- readRDS("pneumonia_pathogens.rds") w ...
- C语言之“字符”与“字符串”之间的区别解析
在C语言中,“字符”与“字符串”之间,是有区别的.这一篇文章中,我们将介绍一下,在C语言中的“字符”与“字符串”,它们之间的区别. 首先,一个很明显的区别是: “字符”,使用单引号作为定界符,而“字符 ...
- docker-Harbor仓库映像
部署环境: centos-7.2 docker-engine-1.12.5 docker-compose-1.9.0 harbor-0.5.0 1.下载所需的软件包(以下需要-翻-墙-下载的地方你们自 ...
- SpringMVC(十四):SpringMVC 与表单提交(post/put/delete的用法);form属性设置encrypt='mutilpart/form-data'时,如何正确配置web.xml才能以put方式提交表单
SpringMVC 与表单提交(post/put/delete的用法) 为了迎合Restful风格,提供的接口可能会包含:put.delete提交方式.在springmvc中实现表单以put.dele ...
- Struts2 输入校验(使用编码方式)
一.Struts输入校验 1.创建register.jsp <%@ page language="java" contentType="text/html; cha ...
- 使用kafka-python客户端进行kafka kerberos认证
之前说过python confluent kafka客户端做kerberos认证的过程,如果使用kafka python客户端的话同样也可以进行kerberos的认证,具体的认证机制这里不再描述,主要 ...
- [清华集训2015]灯泡(浙江大学ZOJ 3203 Light Bulb)
Time Limit: 1 Second Memory Limit: 32768 KB Compared to wildleopard's wealthiness, his brother ...
- [转]C/C++实现回调机制的几种方式(回调、槽、代理)
转自:https://www.jianshu.com/p/4f907bba6d5f (1)Callback方式(回调) Callback的本质是设置一个函数指针进去,然后在需要需要触发某个事件时调用该 ...
- MQTT研究之EMQ:【CoAP协议的ECC证书研究】
今天研究的内容,是CoAP这个协议在EMQ消息队列的支持,CoAP是一个受限资源的协议,基于UDP实现的多用于物联网环境的通信协议.相关介绍不多说,可以看RFC. CoAP协议下,基于DTLS通信,同 ...