对于注释的要求

第一: 能够准确反应设计思想和代码逻辑
第二: 能够描述业务含义，使别的程序员能够迅速了解到代码背后的信息。
第三: 能自解释的代码就不要用注释

[javadoc]

幸运的是,java里有强大的javadoc 注释工具

类、类属性、类方法的注释使用 Javadoc 规范，
使用/*内容/格式，不得使用//xxx 方式

所有的抽象方法（包括接口中的方法）必须要用 Javadoc 注释.
除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能。

以下是常见的javadoc 注释

    /** * show 方法的作用简述. * ＜p＞show 方法的详细说明第一行＜br＞ * show 方法的详细说明第二行* @author 作者 (类)* @version 版本号(类)* @see 对类、属性、方法的说明  参考转向，也就是相关主题  * @param 参数名 参数描述 * @return 返回的内容 * @throws 异常类名* @Exception */

方法内部单行注释，使用//注释。
方法内部多行注释使用/* */注释，注意与代码对齐。
所有的枚举类型字段必须要有注释，说明每个数据项的用途。
注释的描述,尽可能的简单,有力专有名词与关键字保持英文原文即可
特殊注释标记: TODO(还没实现的功能) （标记人，标记时间， [预计处理时间]); FIXME(不能工作) （标记人，标记时间， [预计处理时间])

注释的表述

注释代码段式应该注重’为何作’(why),而不是’怎么做’(How)
不准确 : /* 进行io读写操作 */
准确: /* 通过io读写得到XXX文件里的数据 */
使用专业术语

不准确 : /* 获取网络连接的状态 */
准确 : /* TCP 连接状态 */
注释数据声明:
1. 注释数值的单位
2. 对数值的允许范围给出注释
3. 注释编码含义
4. 注释对输入数据的限制
5. 注释’位标志’
6. 注释全局数据
7. 将于变量有关的注释通过变量名关联起来
注释控制结构:

1 应该在每一个if,循环,或者代码段前面加注释
2 应在每个冗长的控制结构之后加上注释
3 区分输入和输出的数据,用 in 或者 out 注释
4 对子程序的局限性,碰到麻烦的行为,就要注释

日志

用stf4j api, 不要使用应用中日志系统（Log4j、 Logback）中的 API，
日志文件推荐至少保存 15 天
对 trace/debug/info 级别的日志输出，必须使用条件输出形式或者使用占位符的方式
可以使用 warn 日志级别来记录用户输入参数错误的情况，避免用户投诉时，无所适从。
生产环境禁止输出 debug 日志；有选择地输出 info 日志；

代码规范 : 关于注释和日志相关推荐

Android生日礼物（含拼图游戏，背景音乐，自动拨号等功能实现）--根据代码规范修改注释以及定义
公司培训了编码规范,回头过来看看我以前写过的代码,着实比较烂,缺少必要的注释,以及对于变量名的定义也不甚规范,故借着此次学习,我重新整理下一篇安卓项目的文章,规范下代码,可以用doxygen生成htm ...
【Python基础学习笔记day05】pycharm注释的作用+单行注释（行注释）+多行注释（块注释）+关于代码规范
注释文章目录注释目标 01. 注释的作用 02. 单行注释(行注释) 在代码后面增加的单行注释 03. 多行注释(块注释) 什么时候需要使用注释? 关于代码规范目标注释的作用单行注释(行注 ...
rmd中无法打开链结r_R语言数据实战 | 代码规范与文档撰写
点击上方"蓝字"带你去看小星星 R语言虽然有着强大的统计分析和绘图功能,但说到底它是一门编程语言.既然如此,那么R语言就有自己的代码规范,这些规范旨在让R学习者养成良好的代码写作习 ...
c++ doxygen 注释规范_[代码规范]Go语言编码规范指导
本规范旨在为日常Go项目开发提供一个代码的规范指导,方便团队形成一个统一的代码风格,提高代码的可读性,规范性和统一性.本规范将从命名规范,注释规范,代码风格和 Go 语言提供的常用的工具这几个方面做一 ...
C/C 代码规范注释有哪些讲究？
如果领导给你一个项目的源码让你阅读,并理解重构代码,但里面一句注释都没有,我想这肯定是之前同事"删库跑路"了. 看一份源码什么很重要?除了各种代码规范之外,还有一个比较重要的就是注 ...
python代码大全中文注释_零基础小白必看篇：Python代码注释规范代码实例解析操作（收藏）...
本文内容主要介绍了Python代码注释规范代码实例解析,通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下!!! 一.代码注释介绍注释就是对代码的解释和说明 ...
浅析C++代码规范注释有哪些讲究？
作为一名合格的C++开发工程师,不仅需要了解清楚开发技术之外,还需要了解清楚C++注释的用法,这是因为注释虽然写起来很痛苦,但对保证代码可读性至关重要. 浅析C++代码规范注释有哪些讲究? 下面的将描 ...
怎么解决缺少java.doc_阿里代码规范检测中方法缺少javadoc注释怎么办
阿里代码规范检测中方法缺少javadoc注释怎么办发布时间:2020-08-12 15:01:48 来源:亿速云阅读:204 作者:小新这篇文章给大家分享的是有关阿里代码规范检测中方法缺少jav ...
给php代码添加规范的注释
更多参考 http://phpdoc.org/docs/latest/index.html 在phpdocumentor中,注释分为文档性注释和非文档性注释. 所谓文档性注释,是那些放在特定关键字前面 ...
python使用符号#表示单行注释-【经济金融及Python应用讲义】Python编程规范之注释...
原标题:[经济金融及Python应用讲义]Python编程规范之注释来源:计量经济学服务中心经济金融及Python应用讲义一.注释 1.为什么需要注释如果代码的编写者在这里添加了备注说明,那么 ...

代码规范 : 关于注释和日志

对于注释的要求

[javadoc]

日志

代码规范 : 关于注释和日志相关推荐

最新文章

热门文章