BlogJava-Johnny's Collections-随笔分类-编程技巧

编写高质量的代码——从命名入手

Johnny.Liang — Thu, 29 Apr 2010 14:54:00 GMT

笔者从事开发多年，有这样一种感觉，查看一些开源项目，如Spring、Apache Common等源码是一件赏心悦目的事情，究其原因，无外两点：1）代码质量非常高；2）命名特别规范（这可能跟老外的英语水平有关）。
要写高质量的代码，不是一件容易的事，需要长年累月的锻炼，是一个量变到质变的过程，但要写好命名，只需要有比较好的英语语法基础和一种自我意识即可轻松达到。本博文将会结合本人的开发经验，总结出若干命名规则，这些命名规则纯属个人的使用习惯，不代表是一种理想的规则，在这里列举出来，供大家交流讨论。

1.切忌使用没有任何意义的英语字母进行命名：
    for(int i=0; i<10; i++) {
        ...
    }
这是在很多教Java基本语法的书上常见的代码片断，作为教学材料，这样写无可厚非，但作为真正的代码编写，程序员必须要养成良好的习惯，不要使用这种没有任何含义的命名方式，这里可以使用“index”。

2.切忌使用拼音，甚至是拼音首字母组合：
    cishu =5; // 循环的次数
    zzje = 1000.00 // 转账金额
笔者在做代码检查的时候，无数次遇到过这样的命名，使人哭笑不得

3.要使用英文，而且要使用准确的英语，无论是拼写还是语法：

名词单数，必须使用单数英文，如Account、Customer。
对于数组，列表等对象集合的命名，必须使用复数，而且最好按照英文的语法基础知识使用准确的复数形式，如 List accounts、Set strategies。
对于boolean值的属性，很多开发人员习惯使用isXXX，如isClose（是否关闭），但这里有两点建议：1）最好不要带“is”，因为JavaBean的规范，为属性生成get/set方法的时候，会用“get/set/is”，上面的例子，生成get/set方法就会变成“getIsClose/isIsClose/getIsClose”，非常别扭；2）由于boolean值通常反映“是否”，所以准确的用法，应该是是用“形容词”，上面的例子，最终应该被改为 closed，那么get/set方法就是“getClosed/isColsed/setClosed”，非常符合英语阅读习惯。

4.方法名的命名，需要使用“动宾结构短语”或“是动词+表语结构短语”，笔者曾看到过千奇百怪的方法命名，有些使用名词，有些甚至是“名词+动词”，而且，如果宾语是一个对象集合，还是最好使用复数：
    createOrder(Order order) good
    orderCreate(Order order) bad
    removeOrders(List orders) good
    removeOrder(List order) bad

5.对于常见的“增删改查”方法，命名最好要谨慎：

增加：最常见使用create和add，但最好根据英语的语义进行区分，这有助于理解，create代表创建，add代表增加。比如，要创建一个Student，用createStudent要比用addStudent好，为什么？想想如果有个类叫Clazz(班级，避开Java关键字），现在要把一个Student加入到一个Clazz，Clazz很容易就定义了一个 addStudent（Student student)的方法，那么就比较容易混淆。
修改：常见的有alter、update、modify，个人觉得modify最准确。
查询：对于获取单个对象，可以用get或load，但个人建议用get，解释请见第7点的说明，对于不分条件列举，用list，对于有条件查询，用search（最好不要用find，find在英文了强调结果，是“找到”的意思，你提供一个“查询”方法，不保证输入的条件总能“找到”结果）。
删除：常见的有delete和remove，但删除建议用delete，因为remove有“移除”的意思，参考Clazz的例子就可以理解，从班级移除一个学生，会用removeStudent。

6.宁愿方法名冗长，也不要使用让人费解的简写，笔者曾经遇到一个方法，判断“支付账户是否与收款账户相同”，结果我看到一个这样的命名：
checkIsOrderingAccCollAccSame(...) 很难理解，我马上把它改为：
isOrderingAccountSameAsCollectionAccount(...)，虽然有点长，但非常容易阅读，而且这种情况总是出现得比较少。

7.如果你在设计业务系统，最好不要使用技术化的术语去命名。笔者曾经工作的公司曾经制订这样的命名规则，接口必须要以“I”开头，数据传输对象必须以“DTO”作为后缀，数据访问对象必须以“DAO”作为后缀，领域对象必须以“DO”作为后缀，我之所以不建议这种做法，是希望设计人员从一开始就引导开发人员，要从“业务”出发考虑问题，而不要从“技术”出发。所以，接口不需要非得以“I”开头，只要其实现类以“Impl”结尾即可（注：笔者认为接口是与细节无关的，与技术无关，但实现类是实现相关的，用技术化术语无可口非），而数据传输对象，其实无非就是保存一个对象的信息，因此可以用“**Info”，如CustomerInfo，领域对象本身就是业务的核心，所以还是以其真实名称出现，比如Account、Customer，至于“DAO”，这一个词来源于J2ee的设计模式，笔者在之前的项目使用“***Repository”命名，意味“***的仓库”，如AccountRepository，关于“Repository”这个词的命名，是来源于Eric Evans的《Domain-Driven Design》一书的仓库概念，Eric Evans对Repository的概念定义是：领域对象的概念性集合，个人认为这个命名非常的贴切，它让程序员完全从技术的思维中摆脱出来，站在业务的角度思考问题。说到这里，可能有人会反驳：像Spring、Hibernate这些优秀的框架，不是都在用“I”作为接口开头，用“DAO”来命名数据访问对象吗？没错！但千万别忽略了语义的上下文，Spring、Hibernate框架都是纯技术框架，我这里所说的场景是设计业务系统。

8.成员变量不要重复类的名称，例如，很多人喜欢在Account对象的成员变量中使用accountId，accountNumber等命名，其实没有必要，想想成员变量不会鼓孤立的存在，你引用accountId，必须是account.accountId，用account.id已经足够清晰了。

“勿以善小而不为，勿以恶小而为之”、“细节决定成败”，有太多的名言告诉我们，要注重细节。一个优秀的程序员，必须要有坚实的基础，而对于命名规则这样容易掌握的基础，我们何不现行？

Johnny.Liang 2010-04-29 22:54 发表评论

“设计”你的代码

Johnny.Liang — Tue, 27 Apr 2010 16:51:00 GMT

今天一个曾经共事的同行问我：“要从编码转为设计，大概需要多长时间？”
我的回答是：“编码本身就是一种设计，你可以设计你的代码。”

其实正如概要设计与详细设计，系统设计与架构设计一样，编码与设计也是没有明显的边界，每个正确成长的程序员，都必须从编码开始，慢慢锻炼抽象思维、逻辑思维、面向对象思维，然后慢慢的过渡到系统设计，再随着经验和知识的积累，慢慢过渡到架构设计。下面我将会以最近的一个手头的编码任务，简单介绍一下如何“设计”你的代码。

任务是这样的，某银行支付系统的客户端接收银行用户录入的转账数据，当转账数据被审批通过后，状态转变为“transfer”，同时，该客户端需要通过JMS以异步的方式向支付系统后台发送一条带有转账记录（Instruction)的消息，后端在接收到信息之后，需要根据Instruction的一些相关信息，首先确定这笔转账数据是直接发送给真正进行转账的清算（Clearing）银行系统，还是停留在后端系统，等待后端系统中需要执行的工作流程（work flow）。而后端系统需要对Instruction执行的工作流程有两个，同时需要根据Instruction的一些相关信息进行选择。
为了简化复杂度，我这里假设系统有一个InstructionHandleMsgDrivenBean，该bean有一个onMessage()方法，所有业务逻辑需要在该方法中实现。

同时解释一下详细的业务细节：

判断Instruction是否需要停留在后端等待执行指定的工作流程有三个条件：xx、yy、zz，当三个条件都为true时，停留。
判断Instruction需要走A流程还是B流程，由4个因素的组合确定，如果用“Y”代表true，“N”代表false，那么由这个四个因素组成的“XXXX”一共有16种组合，不同的组合分别走A和B流程，如：YYNN、YYNY to A，NNYY、NNNY to B，……不累赘。

好了，对于一个纯编程人员来说，拿到这样的需求，感觉逻辑很简单，可以直接编码了，于是，他开始一行一行的编写代码（伪代码）：

public void onMessage(InstructionInfo instructionInfo) {
    if(xx && yy && zz) { // 停留在后端等待执行指定的工作流程
        // 根据每种组合进行条件判断，走哪个流程
        if(a==true && b==true && c==true && d==true {
            ...
        }
        else if(...) {...}
        else if(...) {...}
        ...
        else(...) {...}
    }
}

这种做法是最为开发人员欢迎的，因为它简单、直接，但这种做法也恰恰反映了开发人员的通病——使用Java编写纯面向过程的代码。

好了，说了一大堆，如何“设计”你的代码呢？答案是：使用面向对象思维：

我们拿到需求之后，可以分析，这个需求大体上分为两部分：

判断是否需要停留在后端等待执行指定的工作流程的部分
选择走哪个工作流程的部分

有了这个前提，我可以设计出两个职责单一的对象了：

public class InstructionHandleDecisionMaker {
    public static boolean isHandledByBackEnd(InstructionInfo info) {
        return (isXX(...) && isYY(...) && isZZ(...));
    }

    private booolean isXX(...) {
        //TODO Implement the logic
        return false;
    }
    private booolean isYY(...) {
        //TODO Implement the logic
        return false;
    }
    private booolean isZZ(...) {
        //TODO Implement the logic
        return false;
    }
}

public class InstructionWorkFlowSelector {
    private static Map mapping = new HashMap();
    static {
        mapping.input("YYNN",WorkFlow.A);
        mapping.input("NNYY",WorkFlow.B);
        ...
    }

    public static WorkFlow getWorkFlow(Instruction info) {
        StringBuilder result = new StringBuilder();
        result.append(isA(...)).append(isB(...));
        result.append(isC(...)).append(isD(...));
        return mapping.get(result.toString());
    }
    private static String isA(...) {
        //TODO Implment the logic
        return "N";
    }
    private static String isB(...) {
        //TODO Implment the logic
        return "N";
    }
    private static String isC(...) {
        //TODO Implment the logic
        return "N";
    }
    private static String isD(...) {
        //TODO Implment the logic
        return "N";
    }
}

可以看到，我先按职责划分了类，再按职责抽取了私有方法，“框架”设计好，为了让编译通过，我上面完整的填写了代码的，然后加上TODO标识，然后，我可以编写我的onMessage方法了：

public void onMessage(InstructionInfo instructionInfo) {
    if( InstructionHandleDecisionMaker.isHandledByBackEnd(...) ) {
        WorkFlow wf =InstructionWorkFlowSelector.getWorkFlow(...);
        //TODO Implment the logic
    }
}

到目前为止，我已经用纯面向对象的思维方式“设计”好我的代码了，这时，我思维非常清晰，因而代码结构也非常清晰，职责单一，内聚高，耦合低，最后，我可以根据需求文档的细节（没有描述）慢慢的编写我的实现了。

复杂的事物总是由一些较简单的事物组成，而这些较简单的事物也是由更简单的事物组成，如此类推。因此，在编写代码的时候，先用面向对象的思维把复杂的问题分解，再进一步分解，最后把简单的问题各个击破，这就是一种设计。开发人员只要养成这种习惯，即使你每天都只是做最底层的编码工作，其实你已经在参与设计工作了，随着知识和经验的累积，慢慢的，你从设计代码开始，上升为设计类、方法，进而是设计模块，进而设计子系统，进而设计系统……，最终，一步一步成为一个优秀的架构师。

最后，有一个真理奉献给浮躁的程序员：

优秀的架构师、设计师，必定是优秀的程序员，不要因为你的职位上升了，就放弃编码。

补充说明：本博文纯粹是讨论一种思维习惯，不要把其做法生搬硬套，不管实际情况，直接在编码的时候这样做，不见得是最好的选择。在实际编码中，有如下问题你必须考虑：

你需要考虑业务逻辑的可重用性和复杂程度，是否有必要设计出新的类或抽取新的私有方法来封装逻辑，或者直接在原方法上编码（如果足够简单）。
新的业务逻辑，是否在某些地方已经存在，可以复用，即使不存在，这些逻辑是应该封装到新的类中，还是应该放置到现有的类中，这需要进行清晰的职责划分。
需要在设计和性能上作出权衡。
如果在现成的系统中增加新的功能，而现成系统的编码风格与你想要的相差很远，但你又没有足够的时间成本来进行重构，那么还是应该让你的代码与现成系统保持一致的风格。

Johnny.Liang 2010-04-28 00:51 发表评论