本系列文章由@浅墨_毛星云 出品
文章链接: http://blog.csdn.net/poem_qianmo/article/details/52204224
作者:毛星云(浅墨) 微博:http://weibo.com/u/1723155442
这篇文章,是关于整洁代码函数书写的一些准则。
一、引言
以下引言的内容,有必要伴随这个系列的每一次更新,这次也不例外。
《代码整洁之道》这本书提出了一个观点:代码质量与其整洁度成正比,干净的代码,既在质量上可靠,也为后期维护、升级奠定了良好基础。书中介绍的规则均来自作者多年的实践经验,涵盖从命名到重构的多个编程方面,虽为一“家”之言,然诚有可资借鉴的价值。
但我们知道,很多时候,理想很丰满,现实很骨感,也知道人在江湖,身不由己。因为项目的紧迫性,需求的多样性,我们无法时时刻刻都写出整洁的代码,保持自己输出的都是高质量、优雅的代码。
但若我们理解了代码整洁之道的精髓,我们会知道怎样让自己的代码更加优雅、整洁、易读、易扩展,知道真正整洁的代码应该是怎么样的,也许就会渐渐养成持续输出整洁代码的习惯。
而且或许你会发现,若你一直保持输出整洁代码的习惯,长期来看,会让你的整体效率和代码质量大大提升。
二、本文涉及知识点思维导图
国际惯例,先放出这篇文章所涉及内容知识点的一张思维导图,就开始正文。大家若是疲于阅读文章正文,直接看这张图,也是可以Get到本文的主要知识点的大概。
三、整洁代码的函数书写准则
函数的第一规则是要短小。第二规则还是要短小。
《代码整洁之道》一书作者Bob大叔写道,“近40年来,我写过各种长度不同的函数。我写过令人憎恶的长达3000行的厌物,也写过许多100行到300行的函数,还写过20行到30行的。经过漫长的试错,经验告诉我,函数就该短小”。
那么函数应该有多短小合适呢?通常来说,应该短于如下这个函数:
- 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( );
- }
而其实,最好应该缩短成如下的样子:
- public static StringrenderPageWithSetupsAndTeardowns(
- PageDatapageData, boolean isSuite) throws Exception
- {
- if(isTestPage(pageData))
- includeSetupAndTeardownPages(pageData,isSuite);
- returnpageData.getHtml( );
- }
总之,十行以内是整洁的函数比较合适的长度,若没有特殊情况,我们最好将单个函数控制在十行以内。
评论区有一些讨论,也放到正文来吧。
“函数是否应该足够短小,算是《代码整洁之道》中最具争议的议题之一。
书写短小函数的时候,其实我们不要忽略一点,那就是,函数名名称本身就具描述性。短小的函数构成,如果要追根溯源了解内部实现,自然需要一层层找到最终的实现。但若是想大致知道这个函数到底做了什么,结合这个短小函数体内具描述性的一些函数名,应该也就一目了然了。试想,当你眼前的这个函数是几十上百上千行的庞然大物的时候,你能做到一眼就一目了然,将其大概做了什么了然于心吗?函数短小的一方面优点,在这里就体现出来了。
函数应该短小这个议题,仁者见仁智者见智,在实际编码过程中任何人都很难做到严格遵守,但大的方向,若想写出整洁的代码,应该去向短小的函数靠拢,对吧?”
函数应该只做一件事情。只做一件事,做好这件事。
设计模式中有单一职责原则,我们可以把这条原则理解为代码整洁之道中的函数单一职责原则。
要判断函数是不是只做了一件事情,还有一个方法,就是看能否再拆出一个函数,该函数不仅只是单纯地重新诠释其实现。
“如果每个例程都让你感到深合己意,那就是整洁的代码。”要遵循这一原则,大半工作都在于为只做一件事的小函数取个好名字。函数越短小,功能越集中,就越便于取个好名字。
别害怕长名称。长而具有描述性的名称,比短而令人费解的名称好。而且长而具有描述性的名称,比描述性的长注释要好。且选择描述性的名称能理清你关于模块的设计思路,并帮你改进之。当然,如果短的名称已经足够说明问题,还是越短越好。
命名方式要保持一致。使用与模块名一脉相承的短语、名词和动词给函数命名。比如,includeSetupAndTeardownPages,includeSetupPages, includeSuiteSetupPage, and includeSetupPage等。这些名词使用了类似的措辞,依序讲述一个故事,就是是比较推崇的命名方式了。
最理想的函数参数形态是零参数,其次是单参数,再次是双参数,应尽量避免三参数及以上参数的函数,有足够的理由才能用三个以上参数(多参数函数)。
函数参数中出现标识符参数是非常不推崇的做法。有标识符参数的函数,很有可能不止在做一件事,标示如果标识符为true将这样做,标识符为false将那样做。正确的做法应该将有标识符参数的函数一分为二,对标识符为true和false分别开一个函数来处理。
重复的代码会导致模块的臃肿,整个模块的可读性可能会应该重复的消除而得到提升。
其实可以这样说,重复可能是软件中一切邪恶的根源,许多原则与实践规则都是为控制与消除重复而创建的。仔细想一想,面向对象编程是如何将代码集中到基类,从而避免了冗余的。而面向方面编程(Aspect Oriented Programming)、面向组件编程(ComponentOriented Programming)多少也是消除重复的一种策略。这样看来,自子程序发明以来,软件开发领域的所有创新都是在不断尝试从源代码中消灭重复。
重复而啰嗦的代码,乃万恶之源,我们要尽力避免。
四、范例
有必要贴出一段书中推崇的整洁代码作为本次函数书写准则的范例。
上面这段代码,满足了函数书写短小、单一职责、命名合适、参数尽可能少、不重复啰嗦这几条准则。整洁的函数代码大致如此。
- 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");
- }
- }
五、小结
大师级程序员把系统当作故事来讲,而不是当做程序来写。这是之前已经提到过的一个观点。
本文讲述了如何编写良好函数的一些准则,如果你遵循这些准则,函数就会短小,有个好名字,而且被很好的归置。不过永远不要忘记,我们真正的目标在于讲述系统的故事,而你编写的函数必须干净利落的拼装到一起,形成一种精确而清晰的语言,帮助你讲故事。
程序员,其实是故事家。
六、本文涉及知识点提炼整理
整洁代码的函数书写,可以遵从如下几个原则:
- 第一原则:短小。若没有特殊情况,最好将单个函数控制在十行以内。
- 第二原则:单一职责。函数应该只做一件事情。只做一件事,做好这件事。
- 第三原则:命名合适且具描述性。长而具有描述性的名称,比短而令人费解的名称好。当然,如果短的名称已经足够说明问题,还是越短越好。
- 第四原则:参数尽可能少。最理想的函数参数形态是零参数,其次是单参数,再次是双参数,应尽量避免三参数及以上参数的函数,有足够的理由才能用三个以上参数。
- 第五原则:尽力避免重复。重复的代码会导致模块的臃肿,整个模块的可读性可能会应该重复的消除而得到提升。