方法的注释
:
1.
清楚地表述出方法的功能，即该方法做什么。不用表述怎么做（怎么做是算法层面的东西，如果算法有一定的复杂度，在其它文档表述，如流程图、算法、序列图等）。注意点是：方法可能实现多个相关功能，要表述每个功能的激活条件（即输入参数的特征），及相应的功能。
若该方法与其它若干个方法相关，要将它们的关联性表述出来，这对于理解整个类的行为很关键。特别是，当对象有状态时，这时该方法的调用可能要依赖于其它方法的先行调用（即对象的当前状态），对象的状态改变及方法的依赖关系是必须描述清楚的。
方法的功能点是指外部可观察的行为：如方法的返回值；方法做的日志；如果有输入参数，方法的输入
—
〉返回的对应关系；产生的异常及其原因；方法的前置依赖；方法造成的对象状态改变（后置状态）等。
输入参数的有效性要表述吗？异常需要表述吗
?
视情况而定，如果情况复杂，特别是异常的产生的原因复杂，需要较多的话才能表述清楚，就需要表述。
2.
输入参数：包括参数的含义，及有效性格式。如果某个参数的有效性方法内部不作检查，要清晰地说明，这意味着调用者自己要保证参数的有效性，不然会造成不确定的错误。通常，这种情况出现在从外部传入大量的数据，并且对数据有效性检查很烦琐，这时可以在系统入口进行有效性检查，系统内部的方法就不再进行检查了。
3.
返回参数：包括参数的含义，可能会有多个不同的返回值，通常是一个有效返回和一个异常返回，对于异常返回，要表述其对应的输入参数。
4.
抛出异常：表述产生各个异常产生的原因。
表述的清晰性检查：
1．
用举例来辅助说明一些文字表述较困难的思想
2．
要注意分段，跟写文章一样，当注释很长时，要有分段。
3．
与单元测试对应性，方法的每个功能点都应该有相应的单元测试对应
4．
方法之间的依赖关系也是功能点，应该有相应的单元测试。
单元测试的注释：
1
．测试函数名：
test+
方法名
+
分类
+
数字编号，分类是
Right-Correct
的全称，数字编号是该分类的测试用例编号。如测试
mutiple
的一个测试函数可命名为
testMultipleRight1
。
2
．
描述：测试哪个功能点？测试哪个参数有效性格式？测试哪个方法依赖性？测试哪个异常？（这些与方法的注释对应）
输入参数：
输出结果：
当被测试方法的输入、输出不那么明显时，也就是说可能没有输入参数或者没有返回值时，输入、输出中则视情况而写。
输入：为测试准备的前提条件（可以是事件）。
输出： 测试期望得到的结果，不一定是返回值。
|