代码整洁之道 总结

1.什么样的代码才是整洁的

从字面意思上理解,整洁的代码,对于程序员来说非常的一目了然,简单、整洁,结构清晰,逻辑清楚。代码其实是一种语言,传递的是逻辑,如果这份代码可以像我们说话一样快速的将逻辑传递给读者,那么这样一份代码就是一份整洁的代码。可以借助沃德原则:"如果每段代码欧让你感到深合已意,那就是整洁代码"

 

2.如何保持代码整洁

首先便是要有保持代码整洁的意识,书中反复提到的提到的一条童子军军规:让营地比你来时更干净。要写好整洁的代码,需要我们心中有着一个意识,我要写好我的代码,我的代码要让自己和别人看着舒服。

 

3.命名

3.1 介绍

软件中命名随处可见,包括变量、函数、参数、类、目录等等,我们就像是一个父亲,给自己的孩子取一个让别人看到就知道的名字。

3.2 名副其实

通过名称就知道要表达的意思。例如:表示已经消逝的时间天数,使用elapsetimeInDays就比d好得多。表示插入数据成功,用insertSuccess就比flag好得多。

3.3 避免误导

命名时避免使用与本意相悖的词。例如:hp,aix,sco不应做变量名,因为它们是UNIX平台的专有名词。使用accountList来指一组账号,除非它真的是List类型。如果容纳账号的容器是Set,那就会引起错误的判断。在命名时最好不要把容器内容带上,使用accountGroup或者bunchOfAccounts更好。

提防使用相差比较小的名称。例如:XYZControllerForEfficentHandingOfStrings和ZYZControllerForEfficientStorageOfStrings。

误导性真正可怕的例子:用小写字母l和大写字母O做变量。

3.4 有意义的区分

光是添加数字或是废话来做区分是远远不够的。

添加数字的反例:Spring中关于属性的拷贝方法 BeanUtils.copyProperties(source,target),参数就使用source和target来表示,而不是a1,a2.

使用废话的反例:存在类名Product,ProductInfo,ProductData。名称不同,但意思无区别。废话都是冗余,Variable永远不该出现在变量名中。

3.5 使用读得出来的名称

例如: (生成日期,年月日时分秒) 变量命名时 gennerationTimeStamp 就比genymdhms好的多,前者比后者读起来好得多,也更好理解。

3.6 使用可搜索的名称

单字母名称和数字常量有个问题,很难在一大篇文字中找出。找MAX_CLASS_PER_STUDENT很容易,想找数字7就很麻烦。单字母名称仅用于短方法中的本地变量。名称长短应与其作用域相对应,比如在一个类中经常使用的,就可以通过大写字母的方式来表示。

3.7 避免使用编码

反例: 变量名加入成员前缀 m_name  表示接口时加上I字母 接口名:IShapeFactory

3.8 避免思维映射

在循环体中通过变量来判断条件时,使用i,j或者k就比其他字母好。千万别用小写字母l和打字字母O。

3.9 类名

类名和对象名应该是名字或者名字短语。如:Customer、WikiPage、Account

3.10 方法名

方法名应该是动词或动词短语,如:postPayment,deletePage或save。

3.11 别扮可爱

例如: 将数据一半进行删除 deleteHalfData 就比 ringingFinger(打响指) 好,只有看过复联的人才知道。

3.12 每个概念对应一个词

给每个抽象概念选一个词,并且一以贯之。例如:插入统一同insert或者save。不要有时用insert,有时用save.

3.13 别用双关语

例如:在一个类中有两个add方法。一个是求和,一个是添加数据。要么把求和改成sum,要么把添加数据改成append.

3.14 使用解决方法领域名称

只有程序员才会阅读你的代码。根据所涉领域来命名不是最好的方法,可以用一些计算机科学术语,算法名,模式名,数学术语来命名。例如:AccountVisitor,JobQueue

3.15 使用源自所涉问题领域的名称

如果不能使用程序猿熟悉的术语来命名,那就采用所设计问题领域的名称来命名吧。至少,维护代码的程序猿可以去请求领域专家。

3.16 添加有意义的语境

很少有名称是能自我说明的。你需要用有良好命名的类,函数或名称空间来放置名称,给读者提供语境。

例如: 有名为firstName,lastName,street,houseNumber,city,state和zipcode的变量,当它们一起出现时,很明确构成一个地址。但如果是state单独出现时,就很难推断时表示地址了。可以通过addrState来标识。更好的方案是将类命名为Address。

3.17 不要添加没用的语境

假设有一个名为“豪华版加油站”(Gas Station Deluxe)的应用,在其中给每个类加上GSD前缀就不是一个好点子。只要短名称足够清楚,就不要添加不必要的语境。

例如:GSDAccountAddress 就可以改成 AccountAddress

3.18 小结

我们有时候会怕其他开发者反对重命名。如果讨论一下就知道,如果名称改的更清楚,其实大家都会感激你。

 

4.函数

4.1 短小

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

4.2 只做一件事

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

4.3 每个函数一个抽象层级

要确保函数只做一件事,函数中的语句都要在同一抽象层级上。函数中混杂不同抽象层级,往往让人迷惑。

反例: 一个方法中调用了其他方法.有getHtml()抽象层比较高的,也有PathParser.render(pathPath)抽象层级中等的,也有builder.append("xxxx")抽象层级底层的。

阅读代码时自顶向下阅读。每个函数后面都跟着位于下一个抽象层级的函数。

例如: A方法中调用了B方法。B方法应该跟在A方法后面,如果A中调用了多个方法,这些方法也应该按照一定逻辑顺序排在A后面。

4.4 使用描述性的名称

例如:includeSetupAndTeardownPages、includeSetupPages、includeSuiteSetupPage和includeSetupPage等。看到这些方法名,我们就知道这个方法是在做什么事情了。函数越短小,功能越集中,那就越好取名字。别害怕长名称,长而具有描述的名称,比短小而令人费解的名称好。长而具有描述的名称,要比描述性的长注释好。

4.5 函数参数

最理想的函数是零参数函数,其次是单参数函数,再次是二,应尽量避免三参数函数。参数不易对付,它带有太多概念性。

4.5.1 一元函数

向函数传入单个参数由三种普遍的理由。一个是问关于那个参数的问题,例如 boolean fileExist("MyFile").另一个可能是操作该参数,将其转化成其他东西。例如 UserDTO transfer(User user)。还有一个就是事件,有输出参数无输出参数。程序将函数看作一个事件。

4.5.2 二元函数

有两个参数的函数要比一元函数难懂。例如:writeField(name)比writeField(outputStream,name)好懂。如果可以的话,把outputstream提取成当前类的成员变量,从而无需再传递它。

4.5.3 三元函数

有三个参数的函数要比二元函数难懂的多,排序,琢磨,忽略的问题都会加倍提现,建议在写三元函数前一定要想清楚。

4.5.4 参数对象

如果函数需要三个,或三个以上的参数,就说明其中的一些参数应该封装为类了。例如:Circle makeCircle(double x,double y,double radius) 和Circle makeCircle(Point center,double radius);

4.6 动词与关键字

给函数去个好名字,能较好地解释函数的意图,以及参数的顺序和意图。函数和参数应当形成一种非常良好的动词/名词对形式。例如:writeField(name)就比witre(name)表示的意图更加清晰

4.7 无副作用

副作用是一种谎言。函数承诺只做一件事,但还是会做其他被藏起来的事。例如:

boolean checkPassword(userName,password){

User user = UserGateway.findByName(userName);

if(user == null){

return false;

}

if(password.equals(user.getPassword()){

Session.initialize();

return true;

}

}

在验证用户名和密码的方法中,进行了session的初始化操作,这就是该方法的副作用,方法名并没有暗示会进行session初始化的操作,当某个误信了函数名的调用者想要检查密码时,就可能导致当前session被抹除的风险。可以通过修改方法名为checkPasswordAndInitializeSession(),虽然哪还是违反了"只做一件事"的原则。可以将session的初始化放到另一个方法,将检查密码和初始化session分开,在上层来调用两个方法。

4.8 分隔指令与询问

函数要么做什么事,要么回答什么事,但二者不可兼得。

反例:if(set("username","horizon")).该set方法的逻辑是先判断 是否有username属性,如果有,则设置horizon,返回true,如果没有则返回false.

应该要把判断属性和设置值分两步来做.

if(attributeExists("username")){

setAttribute("username","horizon");

}

4.9 使用异常替代返回错误码

从指令式函数返回错误码轻微违反了指令与询问分隔的规则。

例如: if(deletePage(page) == E_OK) 当返回错误码时,就是在要求调用者根据返回值去处理逻辑。这样会导致深层次嵌套。

直接在deltePage方法中,对错误的逻辑直接抛出异常,就不用去挨个判断返回了.

例如:try{

deletePage(page);

}catch(Exception e){

 

}

4.10 抽离try/catch代码块

try/catch代码块丑陋不堪,它们搞乱了代码结构,把错误处理与正常流程混为一谈。最好把try和catch中的代码块的主体部分抽离出来。

例如:

try{

methodA();

}catch(Exception e){

logError();

}

4.11 错误处理就是一件事

函数应该只做一件事,错误处理就是一件事。

4.12 别重复自己

重复可能是软件中一切邪恶的根源,许多原则与实践规则都是为空志与消除重复而创建。在我们的开发过程中,相同的逻辑可能在多处被使用。这时,我们就应该根据逻辑将相同的逻辑抽离出来。

4.13 小结

遵循这些规则,函数就会短小,有个好名字,就可以被很好的归置。不过永远别忘记,真正的目标在于讲述系统的故事,而你编写的函数必须干净利落地拼装到一起,帮助你讲故事。

 

5.注释

5.1 介绍

注释的恰当用法是弥补我们在用代码表达意图时遭遇的失败,如果你发现自己需要写注释,再想想看是否有办法通过代码来表达。只有代码能忠实地告诉你它做的事情

5.2 注释并不能美化糟糕的代码

写注释的常见动机是糟糕的代码的存在,与其花时间编写解释你搞出的糟糕的代码的注释,不如花时间清洁那堆糟糕的代码。

5.3 用代码来阐述

有时,代码本身不足以解释其行为。但是其可能只有那么一两行,许多程序猿就觉得没有单独抽出去的必要,这种观点纯属错误。

例如:

//check to see if the employee is eligible for full benefits

if((employee.flags & HOURLY_FLAG) && emplyee.age > 65)

代码中对逻辑的判断添加了注释,但是完全有更优的方案,直接把判断的代码抽离成一个方法

if(employee.isEligibleForFullBenefits())

5.4 好注释

有些注释是必须的,也是有利的。不过要记住,唯一真正好的注释是你想办法不去写的注释

5.4.1 法律信息

有时,公司代码规范要求编写与法律有关的注释。如果可能,就指向一份标准许可或其他外部文档,不要把所有条款放在注释中。

5.4.2 提供信息的注释

//Return an instance of the Responder being tested

protected abstract Responder responderInstance(); 这类注释有时管用,但更好的方式是尽量利用函数名称传达信息。比如:将函数名改成responderBeingTested(),注释就是多余的了。

5.4.3 对意图的解释

有时,注释不仅提供了有关实现的有用信息,而且还提供了决定某个决定后面的意图。

//the status of extract,2 means requested,3 means extracting.

int getExtractStatus()

5.4.4 阐释

有时,注释把某些晦涩难懂的参数或返回值的意义翻译为某种刻度形式,也会是有用的。当然,更好的方法是尽量让参数或返回值自身就足够清楚

例如: assertTrue(a.compareTo(b) == 0)  // a == b

5.4.5 警示

有时,用于警告其他程序猿会出现某种后果的注释也是有用的。

例如:

public static SimpleDateFormat makeStadardHttpDateFormat(){

//SimpleDateFormat is not thread safe, so we

//need to create each instance independently

SimpleDateFormat format = new SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss z");

}

5.4.6 todo注释

有时,有理由用//TODO形式在源代码中放置要做的工作列表。

放大:注释可以用来放大某种看来不合理之物的重要性

例如:

String listItemContent = match.group(3).trim();

//the trim is real important.It removes the starting

//spaces that could cause thr item to be recognized

//as another list.

new ListItemWidget(this, listItemContent, this.level + 1);

return buildList(text.substring(match.end()));

公共API中的Javadoc:如果你在编写公共API,就该为它编写良好的Javadoc。就像其他注释一样,Javadoc也可能误导,不实用或者提供错误信息

5.5 坏注释

大多数注释都属此类。通过,坏注释都是糟糕的代码的支撑或借口,或者对错误决策的修正。

5.5.1 喃喃自语

如果知识因为你觉得应该或者因为过程需要就添加注释,那就是无谓之举。如果要写注释,就要话必要的时间写出最好的注释。

5.5.2 多余的注释:

例如:class User {

//the name of user

private String name;

}

5.5.3 误导性注释

有时,尽管初衷可嘉,程序猿还是会写出不够精确的注释,最终导致误导了读者。

5.5.4 循规式注释

所谓每个函数都要有Javadoc或每个变量都要有注释的规矩是不可取的,这类注释徒然让代码变得散乱。

5.5.5 日志式注释

有人在每次编写代码时,在模块开始出添加一条注释,表示本次修改的原因和日期。很久之前没有代码控制仓库还可以理解,不过有了代码仓库之后,这种注释就完全没有必要了。

5.5.6 废话注释

有时,你会看到纯然是废话的注释。

例如:

/**

Default constructor
**/
protected User(){

 

}

5.5.7 位置标记

有时,程序猿喜欢在源代码中标记某个特别位置.

例如:

// Actions //

5.5.8 括号后面的注释

有时,程序猿会在括号后面放置特殊的注释。尽管这对于含有深度嵌套的长函数可能有意义。不过,最好的方法应该是将长函数拆分成一个个短函数

5.5.9 归属与署名

代码仓库能够记住是谁在合适添加了什么,没必要用那些签名来搞脏代码。

5.5.10 注释掉的代码

直接把代码注释掉是讨厌的做法,不用了就直接删掉,有代码仓库帮我们保存,不用留着。

5.5.11 HTML注释

源代码注释中的HTML标记是一种错误的做法,在代码中应避免它。

5.5.12 信息过多

别在注释中添加有趣的历史性话题或无关的细节描述。

5.5.13 不明显的联系

注释及其描述的代码之间的联系应该显而易见。如果你要写注释,至少让读者能看着注释和代码,并且理解注释所谈何物

5.5.14 函数头

短函数不需要太多描述。为只做一件事的短函数选个好名字,通常要比写函数头注释要好

5.5.15 非公共代码中的Javadoc

虽然Javadoc对于公共API非常有用,但对于不打算作公公用途的代码就完全没有必要用Javadoc了。

6.格式

6.1 目的

代码格式很重要,必须严肃对待。或许你认为"代码能工作"才是专业开发着的头等大事。然而,事实并不是这样的,今天编写的功能,下一版可能被修改,原始代码修改之后很久,其代码风格和可读性仍会影响后续开发的人。即便代码不存在,你的风格和律条仍然存活下来。

6.2 垂直格式

大部分出色的系统中,单个文件长度差不多200行-500行左右,尽管这并非不可违背的原则,也应该接受。短文件比长文件易于理解。

6.2.1 向报纸学习

源文件要向报纸那样,名称应当简单且一目了然,源文件最顶部应该给出高层次的概念和算法,细节应该往下逐次展开,直至最底层的函数和细节。

6.2.2 概念间垂直方向上的区隔

代码都是从上往下,从左往右读。每组代码行展示一条完整的思路,这些思路用空白行区隔开。例如:封包声明,导入声明和每个函数之间,都由空白行隔开。

6.2.3 垂直方向上的靠近

如果说空白行隔开了概念,那么靠近的代码则暗示了它们之间的紧密关系,紧密相关的代码应该互相靠近。

例如:同一个概念的方法应该靠近在一起

6.2.4 垂直距离

对于那些关系密切、放置与同一源文件中的概念,它们之前的区隔应成为易懂性的衡量标准,应避免读者在源文件和类中跳来跳去。

1.变量声名:变量声明应尽可能靠近其使用位置 

反例:  

InputStream is = null;

//间隔了十多行代码

is = new FileInputStream("myFile");

2.实体变量:实体变量应该在类的顶部声明

3.相关函数:若某个函数调用了另外一个,就应该把它们放在一起,而且调用者应尽可能在被调用者上面。

4.概念相关:概念相关的代码应该放在一起,相关性越强,彼此之前的距离就该越短。

6.2.5 垂直顺序

我们想自上向下展示函数调用依赖顺序,被调用函数应该在执行调用函数的下面,这样就建立了一种自顶向下贯穿模块的良好信息流。

6.3 横向格式

应该尽力保持代码行短小,一般来说,代码行的长度不要超过120个字符

6.3.1 水平方向上的区隔与靠近

我们使用空格字符将紧密相关的事物连接在一起,也用空格字符把相关性较弱的事物分隔开。

1.赋值:赋值语句的等号两边由空格隔开,因为赋值有两个确定的要素,左边和右边,空格字符加强了分隔效果。

例如: int lineSize = line.length();

2.函数名和参数:不在函数名和左圆括号之间加空格,因为函数与参数密切相关,如果隔开,就会显得没有关系

3.运算符:乘法因子之间不加空格,因为它们具有较高优先级。加减法之前用空格隔开,因为加减法优先级较低

6.3.2 缩进

大多数类声明,不缩进。类的方法相对该类缩进一个层级,方法的实现相对方法声明缩进一个层级。代码块的实现相对于其容器代码块索引一个层级,以此类推。不要在短小的if语句,while循环中违反缩进规则。

反例:public CommentWidget(ParentWidget parent, String text){super(parent, text);}

6.3.3 空范围

有时,while或for语句的语句体为空。我们很容易被while循环语句同一行末尾的分号欺骗,尽量不要这样使用。

反例: while(dis.read(buf, 0, readBufferSize) != -1);

6.4 团队规则

每个程序猿都有自己喜欢的格式规则,但如果在一个团队工作,就是团队说了算。一组开发者应当认同一种格式风格,每个成员都应该采用那种规则。

 

7.对象和数据结构

7.1 数据抽象

对类的设计应该要隐藏具体的实现,隐藏实现关乎抽象。类并不是简单地用取值器和赋值器将其变量推向外间,而是暴露抽象接口,以便用户无需了解数据的实现就能操作数据本体。

例如:

具象点:

public class Point{

public double x;

public double y;

}

抽象点:

public interface Point{

double getX();

double getY();

void setCartesian(double x, double y);

void setPolar(double r, double theta);

}

7.2 数据、对象的反对称性

对象把数据隐藏于抽象之后,暴露操作数据的函数。而数据结构暴露其数据,不提供有意义的函数。它们其实是对立的。

对象和数据结构之间存在二分原理:过程式代码难以添加新数据结构,因为必须修改所有函数。面向对象代码难以添加新函数,因为必须修改所有类。这其实就是一个抽象和具体的一个差异,对象其实是比较抽象的,而数据结构是具体的。

7.3 得墨忒耳律

得墨忒耳律(The Law of Demeter)认为,模块不应了解它所操作对象的内部情形,对象隐藏数据,暴露操作。方法不应调用由任何函数返回的对象的方法,换言之,只跟朋友谈话,不与陌生人谈话。

反例:ctx.getOptions().getScratchDir();因为它调用了getOptions()返回值的getScratchDir()函数。

7.4 数据传送对象

最为精炼的数据结构,是一个只有公共变量、没有函数的类,这种数据结构就是我们用的DTO。在数据库通信、解析传递的参数时,是最常用的。

7.5 小结

对象暴露行为,隐藏数据。便于添加新对象类型而无需修改现有行为,同时也难以在既有对象中添加新行为。

数据结构暴露数据,没有明显的行为。便于向既有数据结构添加新行为,同时也难以向已有函数添加新数据结构。

 

8.错误处理

8.1 使用异常而非返回码

如果我们在某些判断某些操作的执行情况时,手动返回操作成功或者失败。那么就会导致一个问题,我们必须在调用这个方法之后立即检查执行情况。不如直接在操作失败是直接抛出异常,直接调用时不抛异常,就表示操作是成功的

例如: 

public Boolean handle(){

     int x = operation();

     return x > 0;

}

通过operation的返回值来判断是否操作成功,不如在operation内部操作失败时直接抛出异常。

public Boolean handle(){

     operation();

     return true;

}

8.2 先写Try-Catch-Finally语句

异常的好处之一是,它们在程序中定义了一个范围。执行try部分的代码时,你是在表明可随时取消执行,并在catch语句中续接。在编写可能抛出异常的代码时,先写出try-catch-finally语句,这能帮你定义应该需要做什么,无论try代码块中执行的代码出什么错都一样。

8.3 使用可控异常时catch链不要过深

当我们在方法里主动throw了一个异常之后,可能catch语句在这个方法的三个层级之上,这意味这每个调用该方法的函数都要修改,捕获新异常。以此类推,最终得到的就是一个从底层贯穿到顶层的修改链。

8.4 给出异常发生的环境说明

你抛出的每个异常,应创建信息充分的错误消息,和异常一起传递出去,包括失败的操作和失败类型。

8.5 定义常规流程

按照8.1所说,使用异常而非返回码,这样的话代码会变得简洁,但是可能会出现下面这种情况。

try{

     MealExpenses expenses = expenseReportDAO.getMeals(employee.getId());

     total += expenses.getTotal;

}catch(MealExpensesNotFound e){

     total += getMealPerDiem();

}

业务逻辑是,如果消耗了餐食,则计入总额。如果没有消耗,则员工得到当日餐食补贴。我们在判断是否消耗餐食时,通过抛出数据没有找到的异常来做逻辑判断,这其实是不合理的。应该在expenseReportDAO.getMeals()方法中,如果没有查询到对应的数据,就返回一个参数补贴的对象,而不是在异常里面去继续处理逻辑。

8.6 别返回null值

要讨论错误处理,就要提及到容易引发错误的做法,返回null值就是其中的一个。我们需要在每次调用都去判断是否为null,其实在增加我们的工作量,如果忘记检查,程序就会失控。不如直接抛出异常或者判处特例对象。

例如:

List<Employee> employees = getEmployees();

if(employees != null){

   for(Employee e : employees){

      System.out.println(e.getName());

}

}

其实,我们只要在getEmployees()方法中,如果结果为null时,返回一个空的List,就没有必要去判断是否为null了

8.7 小结

如果将错误处理隔离看待,独立于主要逻辑之外,我们就能单独处理它,也极大提升了代码的可维护性和整洁性。

9.最终收获

我知道了我要写好我的代码。

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值