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.最终收获
我知道了我要写好我的代码。