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

原文地址：http://blog.csdn.net/poem_qianmo/article/details/52204224

这篇文章，是关于整洁代码函数书写的一些准则。

 

一、引言

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

 

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

 

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

 

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

 

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

 

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

国际惯例，先放出这篇文章所涉及内容知识点的一张思维导图，就开始正文。大家若是疲于阅读文章正文，直接看这张图，也是可以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");       }   }   上面这段代码，满足了函数书写短小、单一职责、命名合适、参数尽可能少、不重复啰嗦这几条准则。整洁的函数代码大致如此。

 

五、小结

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

 

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

 

程序员，其实是故事家。

 

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

 

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

第一原则：短小。最好将单个函数控制在十行以内。第二原则：单一职责。函数应该只做一件事情。只做一件事，做好这件事。第三原则：命名合适且具描述性。长而具有描述性的名称，比短而令人费解的名称好。当然，如果函数在已经足够说明问题，还是越短越好。第四原则：参数尽可能少。最理想的函数参数形态是零参数，其次是单参数，再次是双参数，应尽量避免三参数及以上参数的函数，有足够的理由才能用三个以上参数。第五原则：尽力避免重复。重复的代码会导致模块的臃肿，整个模块的可读性可能会应该重复的消除而得到提升。

这篇文章，是关于整洁代码函数书写的一些准则。

 

一、引言

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

 

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

 

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

 

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

 

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

 

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

国际惯例，先放出这篇文章所涉及内容知识点的一张思维导图，就开始正文。大家若是疲于阅读文章正文，直接看这张图，也是可以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");       }   }   上面这段代码，满足了函数书写短小、单一职责、命名合适、参数尽可能少、不重复啰嗦这几条准则。整洁的函数代码大致如此。

 

五、小结

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

 

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

 

程序员，其实是故事家。

 

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

 

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

第一原则：短小。最好将单个函数控制在十行以内。第二原则：单一职责。函数应该只做一件事情。只做一件事，做好这件事。第三原则：命名合适且具描述性。长而具有描述性的名称，比短而令人费解的名称好。当然，如果函数在已经足够说明问题，还是越短越好。第四原则：参数尽可能少。最理想的函数参数形态是零参数，其次是单参数，再次是双参数，应尽量避免三参数及以上参数的函数，有足够的理由才能用三个以上参数。第五原则：尽力避免重复。重复的代码会导致模块的臃肿，整个模块的可读性可能会应该重复的消除而得到提升。