打字猴:1.70045338e+09
1700453380 (4)过时的注释
1700453381
1700453382 注释与代码的版本不一致,注释是1.0版本,而代码早已窜到了5.0版本,相信读者对此类注释深有感触:代码一直在升级,但注释永远保持不变,直到有一天,某一个“粗心”的家伙根据注释修正了一个代码缺陷,然后发现产生了连锁的缺陷反应才知道“代码世界”已经早已发生了变化,而此处的注释只是描述了最原始的信息。
1700453383
1700453384 这类注释不仅仅会出现在你我的代码中,同时也会出现在一些非常著名的开源系统中,毕竟注释不参与运行,只是给人看的,修改代码而不修改注释照样可以运行,添加注释只是“额外任务”而已。解决此类问题的最好办法就是保持注释与代码同步。
1700453385
1700453386 (5)大块注释代码
1700453387
1700453388 可能是为了考虑代码的再次利用,有些大块注释掉的代码仍然保留在生产代码中,这不是一个好的习惯,大块注释代码不仅仅影响代码的阅读性,而且也隔断了代码的连贯性,特别是在代码中的间隔性注释,更增加了阅读的难度,会使Bug隐藏得更深。
1700453389
1700453390 此类注释代码完全可以使用版本管理来实现,而不是在生产代码中出现。这里要注意的是,如果代码临时不用(可能在下一版本中使用,或者在生产版本固化前可能会被使用),可以通过注释来解决,如果是废弃(在生产版本上肯定不用该代码),则应该完全删除掉。
1700453391
1700453392 (6)流水账式的注释
1700453393
1700453394 比如有这样的注释:
1700453395
1700453396 /**
1700453397
1700453398 *2010-09-16张三创建该类,实现XX算法
1700453399
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
[ 上一页 ]  [ :1.70045338e+09 ]  [ 下一页 ]