阿里巴巴Java开发手册学习小结7-注释规约
来源:互联网 发布:淘宝卖特产没证可以吗 编辑:程序博客网 时间:2024/06/05 19:42
本次学习 来源 阿里巴巴Java开发手册 ,文档更新时间2016.12.7 是阿里巴巴集团技术部 首次向Java业界公开,如果有需要开发手册源文档的,欢迎联系
要养成良好的代码注释习惯~
编程规范
注释规约
1.【强制】类,类属性,类方法的注释必须使用javadoc 规范,使用/* 内容/ 格式,不得使用//xxx 方式
2.【强制】所有的抽象方法(包括接口中的方法)必须要用javadoc 注释,除了返回值,参数,异常说明外,还必须指出该方法做什么事情,实现什么功能。
说明:如有实现和调用注意事项,请一并说明。
3.【强制】所有的类都必须添加创建者信息
4.【强制】方法内部单行注释,在被注释语句上方另起一行,使用// 注释。方法内部多行注释使用/**/注释,注意与代码对齐。
5.【强制】所有枚举类型字段必须要有注释,说明每个数据项的用途。
6.【推荐】与其半吊子英文注释,不如用中文注释把问题说清楚,专有名词,关键字,保持英文原文即可。
7.【推荐】代码修改的同时,注释也要进行相应的修改,尤其是参数、返回值、异常、核心逻辑等的修改。
8.【参考】注释掉的代码尽量要配合说明,而不是简单的注释掉。
说明:代码被注释掉有两种可能性:1,后续会恢复此段代码逻辑,2,永久不用。前者如果没有备注信息,难以知晓注释动机,后者建议直接删掉(代码仓库保存了历史代码)
9.【参考】对于注释的要求:
- 第一 能够准确反应设计思想和代码逻辑;
- 第二 能够描述业务含义,使别的程序员能够迅速了解到代码背后的信息。
说明:完全没有注释的打断代码对于阅读者形同天书,注释是给自己看的,即使隔了很长时间,也能清晰理解当时的思路;注释也是给继任者看的,使其能够快速接替自己的工作。
10.【参考】好的命名、代码结构是自解释的,注释力求精简准确、表达到位。避免出现注释的一个极端:过多过滥的注释,代码的逻辑一旦修改,修改注释是相当大的负担
11.【参考】特殊注释标记,请注明标记人与标记时间。注意及时处理这些标记,通过标记扫描,经常清理此类标记。线上故障有时候就是来源于这些标记处的代码。
1 待办事宜(TODO):( 标记人,标记时间,[预计处理时间])
表示需要实现,但目前还未实现的功能。这实际上是一个javadoc的标签,目前的javadoc还没有实现,但已经被广泛使用。只能应用于类,接口和方法(因为它是一个javadoc标签)。2 错误,不能工作(FIXME):(标记人,标记时间,[预计处理时间])
在注释中用FIXME标记某代码是错误的,而且不能工作,需要及时纠正的情况
- 阿里巴巴Java开发手册学习小结7-注释规约
- 阿里巴巴Java开发手册学习小结2-格式规约
- 阿里巴巴Java开发手册学习小结3-OOP规约
- 阿里巴巴Java开发手册- 编程规约-注释规约
- 阿里巴巴Java开发手册学习-OOP规约
- 阿里巴巴Java开发手册学习笔记-编程规约
- 【JAVA-规约】阿里巴巴JAVA开发手册
- 阿里巴巴Java开发手册- 编程规约-其他
- 阿里巴巴Java开发手册-安全规约
- 阿里巴巴Java开发手册-安全规约
- 阿里巴巴Java开发手册编程规约
- 阿里巴巴Java开发手册-命名规约
- 阿里巴巴Java开发手册-命名规约
- 白话阿里巴巴Java开发手册(编程规约)
- 阿里巴巴Java开发手册-编程规约
- 阿里巴巴Java开发手册-命名规约
- 阿里巴巴Java开发手册-命名规约
- 阿里巴巴Java开发手册-命名规约
- webstorm下scss文件 编译成微信小程序wxss文件
- python 读取Linux服务器上的文件
- Android百分比布局
- 通过RSRP和SINR判断LTE信号质量
- 训练营第五天实训
- 阿里巴巴Java开发手册学习小结7-注释规约
- web前后台乱码总结
- Effective Java之避免创建不必要的对象(五)
- CIFAR-10驱动的KNN分类器
- libux创建逻辑卷及扩展
- Jsoup通过URL获取文档,获取href属性内容
- caffe移植到mxnet
- Windows套接字I/O模型(3) -- WSAAsyncSelect模型
- 利用JS实现复选框一键全选/全不选