代码的坏味道(13)——过多的注释(Comments)

发布时间:2017-1-22 3:40:55 编辑:www.fx114.net 分享查询网我要评论
本篇文章主要介绍了"代码的坏味道(13)——过多的注释(Comments) ",主要涉及到代码的坏味道(13)——过多的注释(Comments) 方面的内容,对于代码的坏味道(13)——过多的注释(Comments) 感兴趣的同学可以参考一下。

坏味道——过多的注释(Comments)

特征

注释本身并不是坏事。但是常常有这样的情况:一段代码中出现长长的注释,而它之所以存在,是因为代码很糟糕。

img

问题原因

注释的作者意识到自己的代码不直观或不明显,所以想使用注释来说明自己的意图。这种情况下,注释就像是烂代码的除臭剂。

最好的注释是为函数或类起一个恰当的名字。

如果你觉得一个代码片段没有注释就无法理解,请先尝试重构,试着让所有注释都变得多余。

解决方法

  • 如果一个注释是为了解释一个复杂的表达式,可以运用 提炼变量(Extract Variable) 将表达式切分为易理解的子表达式。
  • 如果你需要通过注释来解释一段代码做了什么,请试试 提炼函数(Extract Method)
  • 如果函数已经被提炼,但仍需要注释函数做了什么,试试运用 函数改名(Rename Method) 来为函数起一个可以自解释的名字。
  • 如果需要对系统某状态进行断言,请运用 引入断言(Introduce Assertion)

收益

  • 代码变得更直观和明显。

何时忽略

注释有时候很有用:

  • 当解释为什么某事物要以特殊方式实现时。
  • 当解释某种复杂算法时。
  • 当你实在不知可以做些什么时。

重构方法说明

提炼变量(Extract Variable)

问题

你有个难以理解的表达式。

void renderBanner() {  if ((platform.toUpperCase().indexOf("MAC") > -1) &&       (browser.toUpperCase().indexOf("IE") > -1) &&        wasInitialized() && resize > 0 )  {    // do something  }}

解决

将表达式的结果或它的子表达式的结果用不言自明的变量来替代。

void renderBanner() {  final boolean isMacOs = platform.toUpperCase().indexOf("MAC") > -1;  final boolean isIE = browser.toUpperCase().indexOf("IE") > -1;  final boolean wasResized = resize > 0;  if (isMacOs && isIE && wasInitialized() && wasResized) {    // do something  }}

提炼函数(Extract Method)

问题

你有一段代码可以组织在一起。

void printOwing() {  printBanner();  //print details  System.out.println("name: " + name);  System.out.println("amount: " + getOutstanding());}

解决

移动这段代码到一个新的函数中,使用函数的调用来替代老代码。

void printOwing() {  printBanner();  printDetails(getOutstanding());}void printDetails(double outstanding) {  System.out.println("name: " + name);  System.out.println("amount: " + outstanding);}

函数改名(Rename Method)

问题

函数的名称未能恰当的揭示函数的用途。

class Person {  public String getsnm();}

解决

修改函数名。

class Person {  public String getSecondName();}

引入断言(Introduce Assertion)

问题

某一段代码需要对程序状态做出某种假设。

double getExpenseLimit() {  // should have either expense limit or a primary project  return (expenseLimit != NULL_EXPENSE) ?    expenseLimit:    primaryProject.getMemberExpenseLimit();}

解决

以断言明确表现这种假设。

double getExpenseLimit() {  Assert.isTrue(expenseLimit != NULL_EXPENSE || primaryProject != null);  return (expenseLimit != NULL_EXPENSE) ?    expenseLimit:    primaryProject.getMemberExpenseLimit();}

注:请不要滥用断言。不要使用它来检查”应该为真“的条件,只能使用它来检查“一定必须为真”的条件。实际上,断言更多是用于自我检测代码的一种手段。在产品真正交付时,往往都会消除所有断言。


后记

一些朋友对我这篇文字有很多质疑。
在这里,我想集中再强调一下我的观点,避免让大家有歧义。
注释的作用,很多时候,非常类似于马路上的警示牌:“前方有坑,悠着点!”难道因为有了警示牌,就不用把坑给填上了吗?但是,在坑没有填上之前,把警示牌给撤了或者压根就没想要立个警示牌,这就更加不应该了。
不知我这么说,大家是否更容易理解。

引申阅读

欢迎继续阅读 代码的症与药 系列文章。

上一篇:react动画难写?试试react版transformjs
下一篇:张辉:工作几年就应该给自己“清零”

相关文章

相关评论