关于注释

2019独角兽企业重金招聘Python工程师标准>>>

代码注释是架起程序设计者与程序阅读者之间的通信桥梁，最大限度的提高团队开发合作效率。也是程序代码可维护性的重要环节之一。所以我们不是为写注释而写注释。下面说一下我们在诉求网二期开发中使用的代码注释规范，供大家参考下。 原则： 1、注释形式统一 在整个应用程序中，使用具有一致的标点和结构的样式来构造注释。如果在其它项目中发现它们的注释规范与这份文档不同，按照这份规范写代码，不要试图在既成的规范系统中引入新的规范。 2、注释内容准确简洁 内容要简单、明了、含义准确，防止注释的多义性，错误的注释不但无益反而有害。 注释条件： 1、基本注释（必须加） (a) 类（接口）的注释 (b) 构造函数的注释 (c) 方法的注释 (d) 全局变量的注释 (e) 字段/属性的注释 备注：简单的代码做简单注释，注释内容不大于10个字即可，另外，持久化对象或VO对象的getter、setter方法不需加注释。具体的注释格式请参考下面举例。 2、特殊必加注释（必须加） (a) 典型算法必须有注释。 (b) 在代码不明晰处必须有注释。 (c) 在代码修改处加上修改标识的注释。 (d) 在循环和逻辑分支组成的代码中加注释。 (e) 为他人提供的接口必须加详细注释。 备注：此类注释格式暂无举例。具体的注释格式自行定义，要求注释内容准确简洁。 注释格式： 1、单行(single-line)注释：“//……” 2、块(block)注释：“/……/” 3、文档注释：“/**……*/” 4、javadoc 注释标签语法 @author 对类的说明 标明开发该类模块的作者 @version 对类的说明 标明该类模块的版本 @see 对类、属性、方法的说明 参考转向，也就是相关主题 @param 对方法的说明 对方法中某参数的说明 @return 对方法的说明 对方法返回值的说明 @exception 对方法的说明 对方法可能抛出的异常进行说明 关于规范：

1. 写干净整洁的代码，请尊重空间，请尊重人眼的偏好 1.1 去除没有用到的类引用，eclipse里面Ctrl+Shilft+O。看到一大片的因为类引用没有用到而报的警告信息简直就是灾难，空间和视觉都没有得到尊重。 1.2 记得格式化代码，eclipse里面Ctrl+Shilft+F。看到一大片杂论无章，连基本的对齐都没有的代码也是很大的灾难，视觉脑力都会受到挑战。 1.3 不要吝惜废弃的老代码，eclipse里面Ctrl+D。有些人对待已经废弃的老代码比对待自己的老婆还宝贝，大量运用注释来保留，随 着代码的演变暂用非常大量的空间。如果那段代码非常精妙，舍不得删，那么请把它移到您的私人代码库。 1.4 请不要写冗余无用的代码。if(true)之类的代码块完全不应该出现，用空行隔开该段代码是更好的选择。 1.5 请合理运用空行。空行可以用来隔开相对独立的代码块，有利于阅读和理解。但是不要使用超过一行的空行，对空间，别太奢侈了。 1.6 请不要在两个地方出现完全相同的代码，您总是可以想办法重用的，不是吗？ 1.7 命名类，方法，变量慎用简写，除非大家都公认。全称我都不一定看得懂，简称您太高估我的智商了！请问qrbs代表什么，可能火星人知道吧！ 1.8 把所有的类变量放到最前面，如果比较多请按用途分组排列，不要把变量散落在大江南北，我找的真的很辛苦！ 1.9 拆分大的类，大的方法，如果您的类有一万行，如果您的方法有一千行，我真的会恐惧，是恐惧！
2. 高效运用注释 2.1 规范的注释类信息。请查看一下Java标准库的String.java源码吧，包括文件名，日期，作者，版本号等信息，用统一的模板。千 万别把您的大名散落于方法签名甚至于具体代码里面了。我在读业务逻辑的时候没有兴趣思考您的人生！要找您我可以在类签名里面找到的，放心啊！ 2.2 非Java Bean的public方法都需要注释，您总不会要别人读您的代码才能调用您的代码吧！即便您的英文非常好，命名也非常规范，您总不能期待别人都英文好，理解都一样吧。 2.3 为不容易理解类变量注释。类变量特别是私有的类变量没有人要求注释，但是为了能够快速的了解您表示的是什么，还是写点什么吧！您知道我英文不算好！ 2.4 注释代码段，注释逻辑选择。上面提到运用空行分割开逻辑相对独立的代码，那么请在空行的下一行也写点下面代码段要干什么的语句吧。 如果有if else等逻辑选择的时候，麻烦也花几秒钟写上判断的依据和结果好吗？逻辑难懂且关键，您懂的！
3. 不断学习，不断思考，不断实践，更上一层楼 3.1 遇到不懂的，请先google，一定要学会，不然就一直不会了，回头发现工作六七年没有工作两年的小朋友懂的多！ 3.2 看别人代码时要汲取好的方法和技巧。 3.3 接触一项技术要升入了解和实践，请问您做过的系统您现在都可以从零开始搭建起来了吗，我的意思是架构搭建哦！ 3.4 书里面有知识，有思想，有时间的话还是多精读几本经典书籍吧。您会受益匪浅！

转载于:https://my.oschina.net/dou2016/blog/739539