【《代码整洁之道》精读与演绎】之三 整洁代码的函数书写准则

时间:2016-08-31来源:网络

  一、引言

  以下引言的内容,有必要伴随这个系列的每一次更新,这次也不例外。

  《代码整洁之道》这本书提出了一个观点:代码质量与其整洁度成正比,干净的代码,既在质量上可靠,也为后期维护、升级奠定了良好基础。书中介绍的规则均来自作者多年的实践经验,涵盖从命名到重构的多个编程方面,虽为一“家”之言,然诚有可资借鉴的价值。

  但我们知道,很多时候,理想很丰满,现实很骨感,也知道人在江湖,身不由己。因为项目的紧迫性,需求的多样性,我们无法时时刻刻都写出整洁的代码,保持自己输出的都是高质量、优雅的代码。

  但若我们理解了代码整洁之道的精髓,我们会知道怎样让自己的代码更加优雅、整洁、易读、易扩展,知道真正整洁的代码应该是怎么样的,也许就会渐渐养成持续输出整洁代码的习惯。

  而且或许你会发现,若你一直保持输出整洁代码的习惯,长期来看,会让你的整体效率和代码质量大大提升。

  二、本文涉及知识点思维导图

  国际惯例,先放出这篇文章所涉及内容知识点的一张思维导图,就开始正文。大家若是疲于阅读文章正文,直接看这张图,也是可以Get到本文的主要知识点的大概。

  

 

  三、整洁代码的函数书写准则

  1 短小

  函数的第一规则是要短小。第二规则还是要短小。

  《代码整洁之道》一书作者Bob大叔写道,“近40年来,我写过各种长度不同的函数。我写过令人憎恶的长达3000行的厌物,也写过许多100行到300行的函数,还写过20行到30行的。经过漫长的试错,经验告诉我,函数就该短小”。

  那么函数应该有多短小合适呢?通常来说,应该短于如下这个函数:

  [cpp] view plain copy print?

  public static StringrenderPageWithSetupsAndTeardowns

  (PageData pageData, boolean isSuite

  )throws Exception

  {

  booleanisTestPage = pageData.hasAttribute("Test");

  if(isTestPage) {

  WikiPagetestPage = pageData.getWikiPage( );

  StringBuffernewPageContent = new StringBuffer( );

  includeSetupPages(testPage,newPageContent, isSuite);

  newPageContent.append(pageData.getContent());

  includeTeardownPages(testPage,newPageContent, isSuite);

  pageData.setContent(newPageContent.toString());

  }

  returnpageData.getHtml( );

  }

  而其实,最好应该缩短成如下的样子:

  [csharp] view plain copy print?

  public static StringrenderPageWithSetupsAndTeardowns(

  PageDatapageData, boolean isSuite) throws Exception

  {

  if(isTestPage(pageData))

  includeSetupAndTeardownPages(pageData,isSuite);

  returnpageData.getHtml( );

  }

  总之,十行以内是整洁的函数比较合适的长度,若没有特殊情况,我们最好将单个函数控制在十行以内。

  评论区有一些讨论,也放到正文来吧。

  “函数是否应该足够短小,算是《代码整洁之道》中最具争议的议题之一。

  书写短小函数的时候,其实我们不要忽略一点,那就是,函数名名称本身就具描述性。短小的函数构成,如果要追根溯源了解内部实现,自然需要一层层找到最终的实现。但若是想大致知道这个函数到底做了什么,结合这个短小函数体内具描述性的一些函数名,应该也就一目了然了。试想,当你眼前的这个函数是几十上百上千行的庞然大物的时候,你能做到一眼就一目了然,将其大概做了什么了然于心吗?函数短小的一方面优点,在这里就体现出来了。

  函数应该短小这个议题,仁者见仁智者见智,在实际编码过程中任何人都很难做到严格遵守,但大的方向,若想写出整洁的代码,应该去向短小的函数靠拢,对吧?”

  2 单一职责

  函数应该只做一件事情。只做一件事,做好这件事。

  设计模式中有单一职责原则,我们可以把这条原则理解为代码整洁之道中的函数单一职责原则。

  要判断函数是不是只做了一件事情,还有一个方法,就是看能否再拆出一个函数,该函数不仅只是单纯地重新诠释其实现。

  3 命名合适且具描述性

  “如果每个例程都让你感到深合己意,那就是整洁的代码。”要遵循这一原则,大半工作都在于为只做一件事的小函数取个好名字。函数越短小,功能越集中,就越便于取个好名字。

  别害怕长名称。长而具有描述性的名称,比短而令人费解的名称好。而且长而具有描述性的名称,比描述性的长注释要好。且选择描述性的名称能理清你关于模块的设计思路,并帮你改进之。当然,如果短的名称已经足够说明问题,还是越短越好。

  命名方式要保持一致。使用与模块名一脉相承的短语、名词和动词给函数命名。比如,includeSetupAndTeardownPages,includeSetupPages, includeSuiteSetupPage, and includeSetupPage等。这些名词使用了类似的措辞,依序讲述一个故事,就是是比较推崇的命名方式了。

  4 参数尽可能少

  最理想的函数参数形态是零参数,其次是单参数,再次是双参数,应尽量避免三参数及以上参数的函数,有足够的理由才能用三个以上参数(多参数函数)。

  函数参数中出现标识符参数是非常不推崇的做法。有标识符参数的函数,很有可能不止在做一件事,标示如果标识符为true将这样做,标识符为false将那样做。正确的做法应该将有标识符参数的函数一分为二,对标识符为true和false分别开一个函数来处理。

  5 避免重复

  重复的代码会导致模块的臃肿,整个模块的可读性可能会应该重复的消除而得到提升。

  其实可以这样说,重复可能是软件中一切邪恶的根源,许多原则与实践规则都是为控制与消除重复而创建的。仔细想一想,面向对象编程是如何将代码集中到基类,从而避免了冗余的。而面向方面编程(Aspect Oriented Programming)、面向组件编程(ComponentOriented Programming)多少也是消除重复的一种策略。这样看来,自子程序发明以来,软件开发领域的所有创新都是在不断尝试从源代码中消灭重复。

  重复而啰嗦的代码,乃万恶之源,我们要尽力避免。

  四、范例

  有必要贴出一段书中推崇的整洁代码作为本次函数书写准则的范例。

  [csharp] view plain copy print?

  using System;

  public class SetupTeardownIncluder

  {

  private PageData pageData;

  private boolean isSuite;

  private WikiPage testPage;

  private StringBuffer newPageContent;

  private PageCrawler pageCrawler;

  public static String render(PageData pageData) throws Exception

  {

  return render(pageData, false);

  }

  public static String render(PageData pageData, boolean isSuite)throws Exception

  {

  return new SetupTeardownIncluder(pageData).render(isSuite);

  }

  private SetupTeardownIncluder(PageData pageData)

  {

  this.pageData = pageData;

  testPage = pageData.getWikiPage();

  pageCrawler = testPage.getPageCrawler();

  newPageContent = new StringBuffer();

  }

  private String render(boolean isSuite) throws Exception

  {

  this.isSuite = isSuite;

  if (isTestPage())

  includeSetupAndTeardownPages();

  return pageData.getHtml();

  }

  private boolean isTestPage() throws Exception

  {

  return pageData.hasAttribute("Test");

  }

  private void includeSetupAndTeardownPages() throws Exception

  {

  includeSetupPages();

  includePageContent();

  includeTeardownPages();

  updatePageContent();

  }

  private void includeSetupPages() throws Exception

  {

  if (isSuite)

  includeSuiteSetupPage();

  includeSetupPage();

  }

  private void includeSuiteSetupPage() throws Exception

  {

  include(SuiteResponder.SUITE_SETUP_NAME, "-setup");

  }

  private void includeSetupPage() throws Exception

  {

  include("SetUp", "-setup");

  }

  private void includePageContent() throws Exception

  {

  newPageContent.append(pageData.getContent());

  }

  private void includeTeardownPages() throws Exception

  {

  includeTeardownPage();

  if (isSuite)

  includeSuiteTeardownPage();

  }

  private void includeTeardownPage() throws Exception

  {

  include("TearDown", "-teardown");

  }

  private void includeSuiteTeardownPage() throws Exception

  {

  include(SuiteResponder.SUITE_TEARDOWN_NAME, "-teardown");

  }

  private void updatePageContent() throws Exception

  {

  pageData.setContent(newPageContent.toString());

  }

  private void include(String pageName, String arg) throws Exception

  {

  WikiPage inheritedPage = findInheritedPage(pageName);

  if (inheritedPage != null)

  {

  String pagePathName = getPathNameForPage(inheritedPage);

  buildIncludeDirective(pagePathName, arg);

  }

  }

  private WikiPage findInheritedPage(String pageName) throws Exception

  {

  return PageCrawlerImpl.getInheritedPage(pageName, testPage);

  }

  private String getPathNameForPage(WikiPage page) throws Exception

  {

  WikiPagePath pagePath = pageCrawler.getFullPath(page);

  return PathParser.render(pagePath);

  }

  private void buildIncludeDirective(String pagePathName, String arg)

  {

  newPageContent

  .append("n!include ")

  .append(arg)

  .append(" .")

  .append(pagePathName)

  .append("n");

  }

  }

  上面这段代码,满足了函数书写短小、单一职责、命名合适、参数尽可能少、不重复啰嗦这几条准则。整洁的函数代码大致如此。

  五、小结

  大师级程序员把系统当作故事来讲,而不是当做程序来写。这是之前已经提到过的一个观点。

  本文讲述了如何编写良好函数的一些准则,如果你遵循这些准则,函数就会短小,有个好名字,而且被很好的归置。不过永远不要忘记,我们真正的目标在于讲述系统的故事,而你编写的函数必须干净利落的拼装到一起,形成一种精确而清晰的语言,帮助你讲故事。

  程序员,其实是故事家。

  六、本文涉及知识点提炼整理

  整洁代码的函数书写,可以遵从如下几个原则:

  第一原则:短小。若没有特殊情况,最好将单个函数控制在十行以内。

  第二原则:单一职责。函数应该只做一件事情。只做一件事,做好这件事。

  第三原则:命名合适且具描述性。长而具有描述性的名称,比短而令人费解的名称好。当然,如果短的名称已经足够说明问题,还是越短越好。

  第四原则:参数尽可能少。最理想的函数参数形态是零参数,其次是单参数,再次是双参数,应尽量避免三参数及以上参数的函数,有足够的理由才能用三个以上参数。

  第五原则:尽力避免重复。重复的代码会导致模块的臃肿,整个模块的可读性可能会应该重复的消除而得到提升。

  本文就此结束。

  下篇文章,我们将继续《代码整洁之道》的精读与演绎,探讨更多的内容。

  Best Wish~

关键词: 代码 函数

加入微信
获取电子行业最新资讯
搜索微信公众号:EEPW

或用微信扫描左侧二维码

相关文章

查看电脑版