避免代码注释的五大理由

3顶
5踩

2013-07-16 09:57 by 副主编 WnouM 评论(20) 有14884人浏览

注释代码编程

代码注释的作用一直以来都被程序员们广泛讨论。很多人认为注释不是必要的，写注释那是因为代码可读性太差了。原文作者Paulo Ortins发表了博文《5 reasons to avoid code comments》，以下为译文：

通常，我们阅读代码比编写代码花费的时间要更多。虽然我从未见过任何科学研究能够证明这一点，但是在软件领域，它就好比一个教条或者信念如此的根深蒂固。因此编写易于阅读的代码就显得尤为重要。程序员可以通过一些技术来实现它，其中一点就包括代码注释。

关于代码注释的文章，网络上有很多讨论。我们应该使用注释来解释代码吗？还是应该注重编写表达式代码而无需阅读注释？Joe Kunk曾发表过一篇文章《To Comment or Not to Comment》其中有段内容是说所谓的好代码是指我们应该避免注释，因为注释通常是用来解释/隐藏恶意代码。

下面就来讨论下避免写代码注释的五大理由：

1. 程序员更加倾向于鼓励”坏“代码。

有一种说法，有代码注释的就是好代码，因此，程序员经常在代码边上写注释，使其看起来更加出色。如果我们把代码注释当做一种信号，那么也许我们正在编写坏代码。每当我们写注释时应该思考如何使代码看清来更加洁净。

2. 花费更多时间来编写和维护

如果注释没有跟随代码的变化而变化，即使是正确的注释也没有用。注释通常作为代码的第二个版本。当为某个函数写注释时我们需要不断的重复自己，这就违反了DRY(Don’t Repeat Yourself) 原则。花费时间来增加复杂性，软件需求改变了，代码也随之跟着变化。如果我们写注释，这就意味着必须去维护注释。因此，除非是很必须要，否则我们应该拒绝在注释上花费双倍时间，相反我们可以利用这些时间来提高代码的质量或开发新的特性。

3. 注释不是测试/验证

修改代码可以依赖工具，比如使用编译器、IDEs及单元测试；而注释却不能。注释没有这些工具，你无法依赖工具或者单元测试在正确的地方或者过期后来确保它们的正确性。一旦你写了注释，没有测试模块来验证它的正确性，一旦这个注释失败了，那么它就永远的失败了。

4. 注释没有代码文档可靠

通常，注释过期后，它们往往与代码失去了连接性。程序员阅读这些注释或许被“欺骗”了。即使不断的更新了代码注释，唯一了解的是这个代码应该是什么以及它的可读性。举个例子，如果老本问我们如果项目发生了更改，我们从哪能看出？是代码还是注释？——答案当然是代码。

5. 代码注释风格填补了屏幕空间

采用标准化的注释尤为重要，某些注释标准（如同下面）使用了很多行，这就要求你尽可能多的阅读更多代码。

/**
*
* @param title The title of the CD
* @param author The author of the CD
* @param tracks The number of tracks on the CD
* @param durationInMinutes The duration of the CD in minutes
*/
public void addCD(String title, String author,int tracks, int durationInMinutes) {
CD cd = new CD();
cd.title = title;
cd.author = author;
cd.tracks = tracks;
cd.duration = duration;
cdList.add(cd);
}

PS：本文所说的“避免代码注释"，并不是说就不写代码注释，而是尽量避免去写代码注释，假如你认为值得也可以这么做。

原文出自：Pauloortins / 译：CSDN

查看图片附件

来自: CSDN

分享到：

3
顶

5
踩

评论共 20 条请登录后发表评论

20 楼 lliiqiang 2014-05-13 16:17

轻松环境要让程序员不分心，否则这种轻松是降低效率反而对于企业不好.

19 楼 justdojava 2013-07-25 09:18

if(i!=我){} 写道

justdojava 写道

代码注释的一大理由

/**
 * @description 一句话描述
 * @task sometask
 * @author justdojava
 * @version 1.0.0-beta
 * @time 2013-7-16
 */

引用

在多人合作的超大项目中，如果有上面的注释，你可以不用通过其他任何项目管理工具，而快速的在代码中全文检索到你在某个时间段对某个版本的某个任务(bug,改进)做了什么。

为什么不用项目管理工具？你能保证你每次都更新？你能指望其他人复制你的代码时正确修改？或者不使坏？

可以使用项目管理工具，但相对于项目管理工具，这种注释在检索时更直观，定位更/快速，相对于不同的项目管理更独立;
每次更新的时候，对外提供的API一般是不会轻易改变的。如果API改变，且不向前兼容，主版本号要更改，只有这种情况下，才会更新注释中的一句话描述。这种情况下，如果都不能保证这种接口性质的注释更新，软件质量堪忧，项目风险堪忧。
复制的代码会重构，且持续重构，以便于可读性和可维护性。如果你有修改这部分代码的权限，在修改后的代码，要找原作者审核。

相对于大量的代码，我更愿意看这个模块的注释和demo,而不愿浪费大量的时间，陷入显然已经稳定代码细节。

18 楼 raymao 2013-07-18 17:39

kidneyball 写道

raymao 写道

xchd 写道

改成 log.debug("开始计算工资") 这个不错，可以使用

而且编译出来的程序还是大个的

等你要在生产环境上排错的的时候你就情愿要大个了。

这个。。。我没有表达不需要写日志的意思

17 楼 laogao3232 2013-07-18 17:04

现在很少写注释了，多是解释业务逻辑的。

16 楼 aegean008 2013-07-18 15:36

注释和文档都很重要。

15 楼 kidneyball 2013-07-17 19:43

raymao 写道

xchd 写道

改成 log.debug("开始计算工资") 这个不错，可以使用

而且编译出来的程序还是大个的

等你要在生产环境上排错的的时候你就情愿要大个了。

14 楼 raymao 2013-07-17 14:55

xchd 写道

改成 log.debug("开始计算工资") 这个不错，可以使用

而且编译出来的程序还是大个的

13 楼 mz0827 2013-07-17 10:35

写注释主要是要把代码实现逻辑给写出来，让读者知道，这段代码是干嘛的。

12 楼 grandboy 2013-07-17 10:32

Checkmate 写道

代碼不需要註釋,好的代碼就是註釋.....
可是...
見到的有些公司明顯只做到了第一點

普遍现象

11 楼 xchd 2013-07-17 09:24

改成 log.debug("开始计算工资") 这个不错，可以使用

10 楼 ququjioulai 2013-07-16 23:38

可读性高最基本就是你英语必须够好，这样对于定义有意义的方法属性大家才能一目了然，如果是java是中文语言，直接就写

数字每月工资=1000;
数字一年工资=计算工资（每月工资，12）；

按照上面写，应该大家都能看懂是啥意思，但是，国人很多英语都很烂的。

9 楼 vcok 2013-07-16 20:51

要么把代码写得足够好，根本不需要注释。要么写得足够差，写多少注释也不管用。我倾向于后者，这样才不会被公司炒掉。

8 楼 Checkmate 2013-07-16 16:58

代碼不需要註釋,好的代碼就是註釋.....
可是...
見到的有些公司明顯只做到了第一點

7 楼 kidneyball 2013-07-16 14:11

我现在团队的做法：
1. 内部注释尽量避免（除非有充分理由且不符合下面列的4种替代方案）
2. API注释尽量详细

代码内部注释替代方案：

1. 用合理的命名达到同样表达效果
2. 如果注释是表示工作流程步骤，用log.debug或log.trace代替
例如 //开始计算工资
改成 log.debug("开始计算工资")
3. 如果注释是表示代码与需求的对应关系，用版本控制工具的提交信息代替（完成一个小需求立刻提交并写好提交信息）
4. 不能用上面1,2,3解决的，把需要注释的代码抽取成独立方法然后在方法上写注释（其实是API文档。如果是私有方法，尽量用合理的方法命名代替）

不能用上面4项解决的，才写内部注释

6 楼 Shen.Yiyang 2013-07-16 14:08

除了java doc，没必要写其他注释。如果代码不能用doc的形式描述，说明设计得非常不好

5 楼 grandboy 2013-07-16 13:53

引用

PS：本文所说的“避免代码注释"，并不是说就不写代码注释，而是尽量避免去写代码注释，假如你认为值得也可以这么做。

绝不做没有意义的事就行了。

4 楼 if(i!=我){} 2013-07-16 11:49

justdojava 写道

代码注释的一大理由

/**
 * @description 一句话描述
 * @task sometask
 * @author justdojava
 * @version 1.0.0-beta
 * @time 2013-7-16
 */

引用

为什么不用项目管理工具？你能保证你每次都更新？你能指望其他人复制你的代码时正确修改？或者不使坏？

3 楼 zhlfz 2013-07-16 10:52

凡事不要说的太绝对，不喜欢注释只要你代码写的让人一看就懂也行，但往往写的代码不加注释自己看的就麻烦。
有时候看到写的烂又不注释的代码只能...

2 楼 justdojava 2013-07-16 10:26

代码注释的一大理由

/**
 * @description 一句话描述
 * @task sometask
 * @author justdojava
 * @version 1.0.0-beta
 * @time 2013-7-16
 */

引用

1 楼 jjihuang 2013-07-16 10:07

很不错的理由！

发表评论

您还没有登录,请您登录后再发表评论

3顶5踩