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
1700453450
/**
1700453451
1700453452
*Note：it is important that the APR_STATUS_IS_EBUSY（s）
1700453453
1700453454
*macro be used to determine
1700453455
1700453456
*if the return value was APR_EBUSY, for portability reasons.
1700453457
1700453458
*@param mutex the mutex on which to attempt the lock acquiring.
1700453459
[
上一页 ]
[ :1.70045341e+09 ]
[
下一页 ]