阅读材料二：代码复审>在需要的地方注释

在需要的地方注释

原文地址:https://courses.edx.org/courses/course-v1:MITx+6.005.1x+3T2016/courseware/Readings_Videos/02-Code-Review/

在需要的地方注释

一个关于注释快速普遍的词.好的程序员在他的代码中写注释,并且写的很合理.好的注释使得代码易懂,远离bug(因为重要的假设已经记录了),和准备改变.

一类重要的注释是说明,一般出现在方法或者类的上方,记录了方法或者类的行为.在Java中,可以很方便地写成一个javadoc式的注释,意思是以/**开头和包含@语法,比如一个方法的@param和@return.这是一个说明的例子:

代码1

说明记录了假设.我们已经提到了说明好几次,并且在将来的阅读材料中也要再提到很多次.

另一类重要的注释是说明一段从别处复制或者采用的代码的出处.这对于实践中的程序员来说非常重要,当你采用网络上发现的代码时.这是一个例子.

代码2

一个记录来源的原因是避免侵权.在StackOverflow上的一小段代码是公共领域的代表,但是从其他地方拷贝的代码可能有所有人或者在某种开源证书之下,意味着一些限制.另一个记录来源的原因是代码可能会过时.StackOverflow上的代码自从第一次被答后的几年内可能有显著的进化.

一些注释是差的和没有必要的.例如,直接将代码翻译成英语,并没有提高易懂性,因为你需要假设你代码的读者至少懂Java.

代码3

但是难懂的代码需要注释:

代码4

dayOfYear的代码需要注释--你会将注释写在哪里?例如,哪里你需要注释月份是从0到11还是1到12的?