注释
编写程序时,总要为程序添加一些注释,用以说明某段代码的作用,或者某个类的用途、某个方法的功能,以及该方法的参数及返回值的意义。
为什么要编写注释?
- 不要太过自信自己的理解能力。当你思路流畅,进入变成境界时,你可能很快地实现某个功能。但在以后再次阅读这段代码时,可能会不知其所以然,因此为了时刻找回当初编程时的思路,建议编写注释。
-
可读性第一,效率第二。如今软件开发愈发复杂,进行一次开发往往不是一个人的工作,需要整个团队协同作战,团队队员之间就需要互相阅读他人的代码,编写注释就是为了能让他人更好更快地理解自己所编写的代码。其次,在后期维护时,仍然可以通过注释来掌握理解程序。从某种角度来说,这同样也提高了团队开发的效率。
-
代码即文档!开发人员编写的源代码也是文档的一部分,我们要把软件里最重要的文档——源代码写规范。
在Java中注释有三种:
- 单行注释: //后面跟上注释内容。
- 多行注释: /* 中间跟上注释内容 。。。。。*/
- 文档注释: /** 。。。注释内容。。。*/
这里多行注释和文档和注释很相似,他们的目的就是为了javadoc程序自动生成文档。
添加注释的原则
代码注释是程序设计者和程序阅读者之间的桥梁,让别人更加容易看懂代码,使团队开发合作大大提高效率,也是程序代码维护性的重要环节之一。所以注释也有原则需要遵守:
1.注释形式统一
在整个应用程序中,使用具有一致的标点和结构的样式来构造注释。如果在其他项目中发现他们的注释规范与这份文档不同,那就按照这份规范写代码,不要试图在继承的规范系统中引入新的规范,以免导致冲突。
2.注释内容要求
内容简单、明了、含义明确,防止注释的多义性、不免错误的注释出现。
注释可以添加的位置
注释可以添加在程序的任意位置,但是我们还是要选择合适的地方插入。一般是添加在类和方法上。
插图:
注释当中可能出现的东西,即java doc标记:
@author ——》开发该类模块的作者,可以多次使用,指明多个作者,每个坐着之间使用逗号(,)分开。
@version——》该类模块的版本,也可以使用多次,但只有第一次有效。
@see——》参考转向,相关的主题
@param对方法中某参数的说明
@return 对方法返回值的说明
@exception 对方法可能抛出的异常进行说明
把注释生成文档的方式
比如用eclipse生成文档:
1、选中要生成文档的类,右键选择Export
2、在弹出框中选择javadoc
3、左侧选择目录,右侧选中要生成文档的类,中间选则public(只有public修饰类和方法可以生成文档);中下这里选中要把文档放的位置。
4、接着点击finish,找到生成文档存放的地方,用浏览器打开