打字猴:1.7004534e+09
1700453400 *2010-10-28李四修正算法中的XXXX缺陷
1700453401
1700453402 *2010-11-30李四重构了XXX方法
1700453403
1700453404 *2011-02-06王五删除了XXXX无用方法
1700453405
1700453406 *2011-04-08马六优化了XXX的性能
1700453407
1700453408 */
1700453409
1700453410 class Foo{
1700453411
1700453412 }
1700453413
1700453414 相信读者看到过很多这样的注释,而且深以为这样的注释是一种好的方式,如果没有版本管理工具,这确实是一种非常好的注释,可以很清晰地看出该类的变化历程,但是有了版本管理工具,此类注释就不应该出现在这里了,应该出现在版本提交的注释上,版本管理可以更加清晰地浏览此类变更历程。
1700453415
1700453416 (7)专为JavaDoc编写的注释
1700453417
1700453418 在注释中加入过多的HTML标签,可以使生成的JavaDoc文档格式整齐美观,这没错,但问题是代码中的注释是给人看的,如果只考虑JavaDoc的阅读者,那代码的阅读者(很可能就是一年后的你)就很难看懂代码上的注释了,能做的办法就是生成JavaDoc文档,然后文档和代码分开来阅读,这是一种让人迅速崩溃的“绝世良药”。
1700453419
1700453420 建议在注释中只保留<p>、<code>等几个常用的标签,不要增加<font>、<table>、<div>等标签。
1700453421
1700453422 解释了这么多不好的注释,那好的注释应该是什么样子的呢?好的注释首先要求正确,注释与代码意图吻合;其次要求清晰,格式统一,文字准确;最后要求简洁,说明该说明的,惜字如金,拒绝不必要的注释,如下类型的注释就是好的注释:
1700453423
1700453424 (1)法律版权信息
1700453425
1700453426 这是我们在阅读源代码时经常看到的,一般都是指向同一个法律版权声明的。
1700453427
1700453428 (2)解释意图的注释
1700453429
1700453430 说明为什么要这样做,而不是怎么做的,比如解决了哪个Bug,方法过时的原因是什么。像这样一个注释就是好的:
1700453431
1700453432 public class BasicDataSource implements DataSource{
1700453433
1700453434 static{
1700453435
1700453436 //Attempt to prevent deadlocks-see DBCP-272
1700453437
1700453438 DriverManager.getDrivers();
1700453439
1700453440 }
1700453441
1700453442 }
1700453443
1700453444 (3)警示性注释
1700453445
1700453446 这类注释是我们经常缺乏的,或者是经常忽视的(即使有了,也常常是与代码版本不匹配),比如可以在注释中提示此代码的缺陷,或者它在不同操作系统上的表现,或者警告后续人员不要随意修改,例如tomcat的源码org.apache.tomcat.jni.Global中有这样一段注释:
1700453447
1700453448 public class Global{
1700453449
[ 上一页 ]  [ :1.7004534e+09 ]  [ 下一页 ]