关闭

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

130人阅读 评论(0) 收藏 举报
分类:


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

 



一、引言



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

 

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

 

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

 

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

 

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

 




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



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

 






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

 


短小


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

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

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

  1. public static StringrenderPageWithSetupsAndTeardowns  
  2. (PageData pageData, boolean isSuite  
  3.        )throws Exception  
  4. {  
  5.        booleanisTestPage = pageData.hasAttribute("Test");  
  6.        if(isTestPage) {  
  7.               WikiPagetestPage = pageData.getWikiPage( );  
  8.               StringBuffernewPageContent = new StringBuffer( );  
  9.               includeSetupPages(testPage,newPageContent, isSuite);  
  10.               newPageContent.append(pageData.getContent());  
  11.               includeTeardownPages(testPage,newPageContent, isSuite);  
  12.               pageData.setContent(newPageContent.toString());  
  13.        }  
  14.        returnpageData.getHtml( );  
  15. }  

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

[csharp] view plain copy
 print?在CODE上查看代码片派生到我的代码片
  1. public static StringrenderPageWithSetupsAndTeardowns(  
  2.        PageDatapageData, boolean isSuite) throws Exception   
  3. {  
  4.        if(isTestPage(pageData))  
  5.               includeSetupAndTeardownPages(pageData,isSuite);  
  6.        returnpageData.getHtml( );  
  7. }  

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


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

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

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

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




 

2 单一职责

 

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

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

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

 

 


命名合适且具描述性

 

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

 

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

 

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

 

 

 

参数尽可能少

 

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


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

 

 

 

5 避免重复


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


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


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

 




四、范例



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

[csharp] view plain copy
 print?在CODE上查看代码片派生到我的代码片
  1. using System;  
  2.   
  3. public class SetupTeardownIncluder  
  4. {  
  5.     private PageData pageData;  
  6.     private boolean isSuite;  
  7.     private WikiPage testPage;  
  8.     private StringBuffer newPageContent;  
  9.     private PageCrawler pageCrawler;  
  10.   
  11.     public static String render(PageData pageData) throws Exception  
  12.     {  
  13.         return render(pageData, false);  
  14.     }  
  15.     public static String render(PageData pageData, boolean isSuite)throws Exception  
  16.     {  
  17.         return new SetupTeardownIncluder(pageData).render(isSuite);  
  18.     }  
  19.     private SetupTeardownIncluder(PageData pageData)  
  20.     {  
  21.         this.pageData = pageData;  
  22.         testPage = pageData.getWikiPage();  
  23.         pageCrawler = testPage.getPageCrawler();  
  24.         newPageContent = new StringBuffer();  
  25.     }  
  26.   
  27.     private String render(boolean isSuite) throws Exception  
  28.     {  
  29.         this.isSuite = isSuite;  
  30.         if (isTestPage())  
  31.         includeSetupAndTeardownPages();  
  32.         return pageData.getHtml();  
  33.     }  
  34.   
  35.     private boolean isTestPage() throws Exception  
  36.     {  
  37.         return pageData.hasAttribute("Test");  
  38.     }  
  39.   
  40.     private void includeSetupAndTeardownPages() throws Exception  
  41.     {  
  42.         includeSetupPages();  
  43.         includePageContent();  
  44.         includeTeardownPages();  
  45.         updatePageContent();  
  46.     }  
  47.   
  48.     private void includeSetupPages() throws Exception  
  49.     {  
  50.         if (isSuite)  
  51.             includeSuiteSetupPage();  
  52.         includeSetupPage();  
  53.     }  
  54.   
  55.     private void includeSuiteSetupPage() throws Exception  
  56.     {  
  57.         include(SuiteResponder.SUITE_SETUP_NAME, "-setup");  
  58.     }  
  59.   
  60.     private void includeSetupPage() throws Exception  
  61.     {  
  62.         include("SetUp""-setup");  
  63.     }  
  64.   
  65.     private void includePageContent() throws Exception  
  66.     {  
  67.         newPageContent.append(pageData.getContent());  
  68.     }  
  69.   
  70.     private void includeTeardownPages() throws Exception  
  71.     {  
  72.         includeTeardownPage();  
  73.         if (isSuite)  
  74.         includeSuiteTeardownPage();  
  75.     }  
  76.   
  77.     private void includeTeardownPage() throws Exception  
  78.     {  
  79.         include("TearDown""-teardown");  
  80.     }  
  81.   
  82.     private void includeSuiteTeardownPage() throws Exception  
  83.     {  
  84.         include(SuiteResponder.SUITE_TEARDOWN_NAME, "-teardown");  
  85.     }  
  86.   
  87.     private void updatePageContent() throws Exception  
  88.     {  
  89.         pageData.setContent(newPageContent.toString());  
  90.     }  
  91.   
  92.     private void include(String pageName, String arg) throws Exception  
  93.     {  
  94.         WikiPage inheritedPage = findInheritedPage(pageName);  
  95.         if (inheritedPage != null)   
  96.         {  
  97.             String pagePathName = getPathNameForPage(inheritedPage);  
  98.             buildIncludeDirective(pagePathName, arg);  
  99.         }  
  100.     }  
  101.   
  102.     private WikiPage findInheritedPage(String pageName) throws Exception  
  103.     {  
  104.         return PageCrawlerImpl.getInheritedPage(pageName, testPage);  
  105.     }  
  106.   
  107.     private String getPathNameForPage(WikiPage page) throws Exception  
  108.     {  
  109.         WikiPagePath pagePath = pageCrawler.getFullPath(page);  
  110.         return PathParser.render(pagePath);  
  111.     }  
  112.   
  113.     private void buildIncludeDirective(String pagePathName, String arg)  
  114.     {  
  115.         newPageContent  
  116.         .append("\n!include ")  
  117.         .append(arg)  
  118.         .append(" .")  
  119.         .append(pagePathName)  
  120.         .append("\n");  
  121.     }  
  122. }  
上面这段代码,满足了函数书写短小、单一职责、命名合适、参数尽可能少、不重复啰嗦这几条准则。整洁的函数代码大致如此。




 

五、小结



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

 

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

 

程序员,其实是故事家。

 




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

 


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

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

 


本文就此结束。

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

Best Wish~

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

 



一、引言



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

 

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

 

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

 

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

 

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

 




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



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

 






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

 


短小


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

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

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

  1. public static StringrenderPageWithSetupsAndTeardowns  
  2. (PageData pageData, boolean isSuite  
  3.        )throws Exception  
  4. {  
  5.        booleanisTestPage = pageData.hasAttribute("Test");  
  6.        if(isTestPage) {  
  7.               WikiPagetestPage = pageData.getWikiPage( );  
  8.               StringBuffernewPageContent = new StringBuffer( );  
  9.               includeSetupPages(testPage,newPageContent, isSuite);  
  10.               newPageContent.append(pageData.getContent());  
  11.               includeTeardownPages(testPage,newPageContent, isSuite);  
  12.               pageData.setContent(newPageContent.toString());  
  13.        }  
  14.        returnpageData.getHtml( );  
  15. }  

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

[csharp] view plain copy
 print?在CODE上查看代码片派生到我的代码片
  1. public static StringrenderPageWithSetupsAndTeardowns(  
  2.        PageDatapageData, boolean isSuite) throws Exception   
  3. {  
  4.        if(isTestPage(pageData))  
  5.               includeSetupAndTeardownPages(pageData,isSuite);  
  6.        returnpageData.getHtml( );  
  7. }  

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


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

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

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

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




 

2 单一职责

 

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

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

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

 

 


命名合适且具描述性

 

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

 

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

 

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

 

 

 

参数尽可能少

 

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


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

 

 

 

5 避免重复


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


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


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

 




四、范例



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

[csharp] view plain copy
 print?在CODE上查看代码片派生到我的代码片
  1. using System;  
  2.   
  3. public class SetupTeardownIncluder  
  4. {  
  5.     private PageData pageData;  
  6.     private boolean isSuite;  
  7.     private WikiPage testPage;  
  8.     private StringBuffer newPageContent;  
  9.     private PageCrawler pageCrawler;  
  10.   
  11.     public static String render(PageData pageData) throws Exception  
  12.     {  
  13.         return render(pageData, false);  
  14.     }  
  15.     public static String render(PageData pageData, boolean isSuite)throws Exception  
  16.     {  
  17.         return new SetupTeardownIncluder(pageData).render(isSuite);  
  18.     }  
  19.     private SetupTeardownIncluder(PageData pageData)  
  20.     {  
  21.         this.pageData = pageData;  
  22.         testPage = pageData.getWikiPage();  
  23.         pageCrawler = testPage.getPageCrawler();  
  24.         newPageContent = new StringBuffer();  
  25.     }  
  26.   
  27.     private String render(boolean isSuite) throws Exception  
  28.     {  
  29.         this.isSuite = isSuite;  
  30.         if (isTestPage())  
  31.         includeSetupAndTeardownPages();  
  32.         return pageData.getHtml();  
  33.     }  
  34.   
  35.     private boolean isTestPage() throws Exception  
  36.     {  
  37.         return pageData.hasAttribute("Test");  
  38.     }  
  39.   
  40.     private void includeSetupAndTeardownPages() throws Exception  
  41.     {  
  42.         includeSetupPages();  
  43.         includePageContent();  
  44.         includeTeardownPages();  
  45.         updatePageContent();  
  46.     }  
  47.   
  48.     private void includeSetupPages() throws Exception  
  49.     {  
  50.         if (isSuite)  
  51.             includeSuiteSetupPage();  
  52.         includeSetupPage();  
  53.     }  
  54.   
  55.     private void includeSuiteSetupPage() throws Exception  
  56.     {  
  57.         include(SuiteResponder.SUITE_SETUP_NAME, "-setup");  
  58.     }  
  59.   
  60.     private void includeSetupPage() throws Exception  
  61.     {  
  62.         include("SetUp""-setup");  
  63.     }  
  64.   
  65.     private void includePageContent() throws Exception  
  66.     {  
  67.         newPageContent.append(pageData.getContent());  
  68.     }  
  69.   
  70.     private void includeTeardownPages() throws Exception  
  71.     {  
  72.         includeTeardownPage();  
  73.         if (isSuite)  
  74.         includeSuiteTeardownPage();  
  75.     }  
  76.   
  77.     private void includeTeardownPage() throws Exception  
  78.     {  
  79.         include("TearDown""-teardown");  
  80.     }  
  81.   
  82.     private void includeSuiteTeardownPage() throws Exception  
  83.     {  
  84.         include(SuiteResponder.SUITE_TEARDOWN_NAME, "-teardown");  
  85.     }  
  86.   
  87.     private void updatePageContent() throws Exception  
  88.     {  
  89.         pageData.setContent(newPageContent.toString());  
  90.     }  
  91.   
  92.     private void include(String pageName, String arg) throws Exception  
  93.     {  
  94.         WikiPage inheritedPage = findInheritedPage(pageName);  
  95.         if (inheritedPage != null)   
  96.         {  
  97.             String pagePathName = getPathNameForPage(inheritedPage);  
  98.             buildIncludeDirective(pagePathName, arg);  
  99.         }  
  100.     }  
  101.   
  102.     private WikiPage findInheritedPage(String pageName) throws Exception  
  103.     {  
  104.         return PageCrawlerImpl.getInheritedPage(pageName, testPage);  
  105.     }  
  106.   
  107.     private String getPathNameForPage(WikiPage page) throws Exception  
  108.     {  
  109.         WikiPagePath pagePath = pageCrawler.getFullPath(page);  
  110.         return PathParser.render(pagePath);  
  111.     }  
  112.   
  113.     private void buildIncludeDirective(String pagePathName, String arg)  
  114.     {  
  115.         newPageContent  
  116.         .append("\n!include ")  
  117.         .append(arg)  
  118.         .append(" .")  
  119.         .append(pagePathName)  
  120.         .append("\n");  
  121.     }  
  122. }  
上面这段代码,满足了函数书写短小、单一职责、命名合适、参数尽可能少、不重复啰嗦这几条准则。整洁的函数代码大致如此。




 

五、小结



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

 

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

 

程序员,其实是故事家。

 




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

 


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

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

 


本文就此结束。

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

Best Wish~

0
0

查看评论
* 以上用户言论只代表其个人观点,不代表CSDN网站的观点或立场
    个人资料
    • 访问:8225次
    • 积分:304
    • 等级:
    • 排名:千里之外
    • 原创:18篇
    • 转载:30篇
    • 译文:0篇
    • 评论:0条
    文章分类