阿里巴巴 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) { ...
随机推荐
- 实践分布式配置中心Apollo
简介 Apollo(阿波罗)是携程框架部门研发的分布式配置中心,能够集中化管理应用不同环境.不同集群的配置,配置修改后能够实时推送到应用端,并且具备规范的权限.流程治理等特性,适用于微服务配置管理场景 ...
- 【技术博客】Django+uginx+uwsgi框架的服务器部署
1.登录服务器 使用ssh来直接登录到服务器terminal进行操作,推荐使用XShell和XFtp来进行远程登录和文件传输. 2.运行环境准备 本组获得的华为云服务器为ubuntu16.04版本,先 ...
- 敏捷项目管理—Scrum框架总结
Scrum中的角色 Scrum Master——项目负责人.项目经理 保护团队不受外界干扰,是团队的领导和推进者,负责提升 Scrum 团队的工作效率,控制 Scrum 中的“检视和适应”周期过程.与 ...
- vue中select设置默认选中
vue中select设置默认选中 一.总结 一句话总结: 通过v-model来:select上v-model的值为option默认选中的那项的值(value) 二.select设置默认选中实例 < ...
- Gevent简明教程
Gevent简明教程 发表于 2015-11-28 | 分类于 技术| | 阅读次数 5159 前述 进程 线程 协程 异步 并发编程(不是并行)目前有四种方式:多进程.多线程.协程和异步. 多 ...
- Mysql:设置主键自动增长起始值
比较郁闷昨天在家使用‘alter table `tablename` AUTO_INCREMENT=10000;’怎么也不起效,但是今天下班时间公司一同事尝试了一下就可以了.搞不明白自己当时是怎么操作 ...
- Java-JUC(十五):synchronized执行流程分析
一.锁对象及 synchronized 的使用 synchronized 通过互斥锁(Mutex Lock)来实现,同一时刻,只有获得锁的线程才可以执行锁内的代码. 锁对象分为两种: 实例对象(一个类 ...
- spring mvc aop拦截controller层获取RequestBody反序列化后参数
最近,为了解耦,把一逻辑从interceptor抽出来,放在aop中处理,需要得到RequestBody.如下: @Aspect @Configuration public class CheckAs ...
- vue-devtools 获取到 vuex store 和 Vue 实例的?
vue-devtools 获取到 vuex store 和 Vue 实例的? https://github.com/vuejs/vue-devtools 安装了 vue-devTools ...
- Sketch2Code - Transform sketches into HTML using AI
Sketch2Code - Transform sketches into HTML using AI https://sketch2code.azurewebsites.net/generated- ...