避免代码注释的五大理由

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

代码注释的作用一直以来都被程序员们广泛讨论。很多人认为注释不是必要的,写注释那是因为代码可读性太差了。原文作者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. 代码注释风格填补了屏幕空间

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

 

  1. /** 
  2. * @param title The title of the CD 
  3. * @param author The author of the CD 
  4. * @param tracks The number of tracks on the CD 
  5. * @param durationInMinutes The duration of the CD in minutes 
  6. */ 
  7.  
  8. public void addCD(String title, String author, 
  9. int tracks, int durationInMinutes) { 
  10. CD cd = new CD(); 
  11. cd.title = title; 
  12. cd.author = author; 
  13. cd.tracks = tracks; 
  14. cd.duration = duration; 
  15. cdList.add(cd); 

原文链接:http://www.html5cn.org/article-5351-1.html

责任编辑:陈四芳 来源: 51CTO
相关推荐

2013-07-17 17:21:49

避免代码注释移动开发移动互联网

2013-09-25 09:58:33

必应

2014-07-11 13:56:16

2010-07-28 16:09:53

苹果

2016-09-29 14:39:01

openSUSELinux版本

2017-08-28 21:50:09

大数据PythonGo语言

2013-09-17 10:14:22

腾讯搜狗

2018-02-10 09:48:04

存储软件理由

2011-02-15 08:39:49

2011-05-18 10:40:19

Windows 7

2011-04-15 10:38:27

VDI

2016-06-30 09:21:33

WindowsLinux系统

2011-05-19 10:20:49

2016-08-10 10:27:30

2012-04-18 09:42:36

数据分析Hadoop

2009-08-27 13:02:43

2016-10-17 09:47:21

2010-07-16 10:14:07

2010-09-02 15:58:46

2022-04-25 12:41:33

SIEM安全信息事件管理安全运营
点赞
收藏

51CTO技术栈公众号