注释本身并不是坏事。但是常常有这样的情况:一段代码中出现长长的注释,而它之所以存在,是因为代码很糟糕。
注释的作者意识到自己的代码不直观或不明显,所以想使用注释来说明自己的意图。这种情况下,注释就像是烂代码的除臭剂。
最好的注释是为函数或类起一个恰当的名字。
如果你觉得一个代码片段没有注释就无法理解,请先尝试重构,试着让所有注释都变得多余。
提炼变量(Extract Variable)
将表达式切分为易理解的子表达式。提炼函数(Extract Method)
。函数改名(Rename Method)
来为函数起一个可以自解释的名字。引入断言(Introduce Assertion)
。注释有时候很有用:
问题
你有个难以理解的表达式。
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 }}
问题
你有一段代码可以组织在一起。
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);}
问题
函数的名称未能恰当的揭示函数的用途。
class Person { public String getsnm();}
解决
修改函数名。
class Person { public String getSecondName();}
问题
某一段代码需要对程序状态做出某种假设。
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();}
注:请不要滥用断言。不要使用它来检查”应该为真“的条件,只能使用它来检查“一定必须为真”的条件。实际上,断言更多是用于自我检测代码的一种手段。在产品真正交付时,往往都会消除所有断言。
一些朋友对我这篇文字有很多质疑。
在这里,我想集中再强调一下我的观点,避免让大家有歧义。
注释的作用,很多时候,非常类似于马路上的警示牌:“前方有坑,悠着点!”难道因为有了警示牌,就不用把坑给填上了吗?但是,在坑没有填上之前,把警示牌给撤了或者压根就没想要立个警示牌,这就更加不应该了。
不知我这么说,大家是否更容易理解。
欢迎继续阅读 代码的症与药 系列文章。
一、不得利用本站危害国家安全、泄露国家秘密,不得侵犯国家社会集体的和公民的合法权益,不得利用本站制作、复制和传播不法有害信息!
二、互相尊重,对自己的言论和行为负责。