1、java代码规范详细版Java代码规范本Java代码规范以SUN的标准Java代码规范为基础,为适应我们公司的实际需要,可能会做一些修改。本文档中没有说明的地方,请参看SUN Java标准代码规范。如果两边有冲突,以SUN Java标准为准。1. 标识符命名规范1.1 概述标识符的命名力求做到统一、达意和简洁。尽量做到每个人按照规范来,多人开发如一人开发一样。1.1.1 统一统一是指,对于同一个概念,在程序中用同一种表示方法,比如对于供应商,既可以用supplier,也可以用provider,但是我们只能选定一个使用,至少在一个Java项目中保持统一。统一是作为重要的,如果对同一概念有不同的表
2、示方法,会使代码混乱难以理解。即使不能取得好的名称,但是只要统一,阅读起来也不会太困难,因为阅读者只要理解一次。1.1.2 达意达意是指,标识符能准确的表达出它所代表的意义,比如: newSupplier, OrderPaymentGatewayService等;而 supplier1, service2,idtts等则不是好的命名方式。准确有两成含义,一是正确,而是丰富。如果给一个代表供应商的变量起名是 order,显然没有正确表达。同样的,supplier1, 远没有targetSupplier意义丰富。1.1.3 简洁简洁是指,在统一和达意的前提下,用尽量少的标识符。如果不能达意,宁愿不
3、要简洁。比如:theOrderNameOfTheTargetSupplierWhichIsTransfered 太长, transferedTargetSupplierOrderName则较好,但是transTgtSplOrdNm就不好了。省略元音的缩写方式不要使用,我们的英语往往还没有好到看得懂奇怪的缩写。1.1.4 骆驼法则Java中,除了包名,静态常量等特殊情况,大部分情况下标识符使用骆驼法则,即单词之间不使用特殊符号分割,而是通过首字母大写来分割。比如: supplierName, addNewContract,而不是 supplier_name, add_new_contract。1
4、.1.5 英文 vs 拼音尽量使用通俗易懂的英文单词,如果不会可以向队友求助,实在不行则使用汉语拼音,避免拼音与英文混用。比如表示归档,用archive比较好, 用pigeonhole则不好,用guiDang尚可接受。1.2 包名使用小写字母如 com.amerisia.ebills,不要 com.amerisia.Ebills单词间不要用字符隔开,比如 com.amerisia.ebills,而不要com.amerisia.ebills _util1.3 类名1.3.1 首字母大写类名要首字母大写,比如 LCIssueInfoManagerEJB, LCIssueAction;不要 lcIs
5、sueInfoManagerEJB, lcIssueAction.1.3.2 后缀类名往往用不同的后缀表达额外的意思,如下表:后缀名意义举例EJB表示这个类为EJB类LCIssueInfoManagerEJBService表明这个类是个服务类,里面包含了给其他类提同业务服务的方法PaymentOrderServiceImpl这个类是一个实现类,而不是接口PaymentOrderServiceImplInter这个类是一个接口LifeCycleInterDao这个类封装了数据访问方法PaymentOrderDaoAction直接处理页面请求,管理页面逻辑了类UpdateOrderListActi
6、onListener响应某种事件的类PaymentSuccessListenerEvent这个类代表了某种事件PaymentSuccessEventServlet一个ServletPaymentCallbackServletFactory生成某种对象工厂的类PaymentOrderFactoryAdapter用来连接某种以前不被支持的对象的类DatabaseLogAdapterJob某种按时间运行的任务PaymentOrderCancelJobWrapper这是一个包装类,为了给某个类提供没有的能力SelectableOrderListWrapperBean这是一个POJOMenuStateB
7、ean1.4 方法名首字母小写,如 addOrder() 不要 AddOrder()动词在前,如 addOrder(),不要orderAdd()查询方法要查询的内容在前,条件在后。 如getXxByXx()动词前缀往往表达特定的含义,如下表:前缀名意义举例create创建createOrder()delete删除deleteOrder()add创建,暗示新创建的对象属于某个集合addPaidOrder()remove删除removeOrder()init或则initialize初始化,暗示会做些诸如获取资源等特殊动作initializeObjectPooldestroy销毁,暗示会做些诸如释放
8、资源的特殊动作destroyObjectPoolopen打开openConnection()close关闭closeConnection() b ) /do something here;2.6.2.2运算符两边用一个空格隔开 例如: 不要写成: 2.6.2.3 逗号语句后如不换行,紧跟一个空格如下:call(a, b, c);不能如下:call(a,b,c);2.6.3 空行的使用空行可以表达代码在语义上的分割,注释的作用范围,等等。将类似操作,或一组操作放在一起不用空行隔开,而用空行隔开不同组的代码, 如图:上例中的空行,使注释的作用域很明显. 连续两行的空行代表更大的语义分割。 方法之间
9、用空行分割(尽量用一行空行) 域之间用空行分割 超过十行的代码如果还不用空行分割,就会增加阅读困难3. 注释规范3.1 注释 vs 代码 注释宜少二精,不宜多而滥,更不能误导 命名达意,结构清晰, 类和方法等责任明确,往往不需要,或者只需要很少注释,就可以让人读懂;相反,代码混乱,再多的注释都不能弥补。所以,应当先在代码本身下功夫。 不能正确表达代码意义的注释,只会损害代码的可读性。 过于详细的注释,对显而易见的代码添加的注释,罗嗦的注释,还不如不写。 注释要和代码同步,过多的注释会成为开发的负担3.2 Java Doc表明类、域和方法等的意义和用法等的注释,要以javadoc的方式来写。Ja
10、va Doc是个类的使用者来看的,主要介绍 是什么,怎么用等信息。凡是类的使用者需要知道,都要用Java Doc 来写。非Java Doc的注释,往往是个代码的维护者看的,着重告述读者为什么这样写,如何修改,注意什么问题等。 如下:类3.3 块级别注释3.3.1 块级别注释,单行时用 /, 多行时用 /* . */。3.3.2 较短的代码块用空行表示注释作用域3.3.3 较长的代码块要用/*- start: -*/和/*- end: -*/包围3.4 行内注释行内注释用 / 写在行尾4 最佳实践和禁忌4.1 每次保存的时候,都让你的代码是最美的程序员都是懒惰的,不要想着等我完成了功能,再来优化
11、代码的格式和结构,等真的把功能完成,很少有人会再愿意回头调整代码。4.2 使用log而不是System.out.println()log可以设定级别,可以控制输出到哪里,容易区分是在代码的什么地方打印的,而System.out.print则不行。而且,System.out.print的速度很慢。所以,除非是有意的,否则,都要用log。至少在提交到svn之前把System.out.print换成log。4.3 每个if while for等语句,都不要省略大括号看下面的代码:if (a b) a+;如果在以后维护的时候,需要在a b 时,把b+,一步小心就会写成:if (a b) a+; b+;
12、这样就错了,因为无论a和b是什么关系,b+都会执行。 如果一开始就这样写:if (a b) a+;相信没有哪个笨蛋会把b+添加错的。而且,这个大括号使作用范围更明显,尤其是后面那行很长要折行时。4.4 善用TODO:在代码中加入 /TODO: ,大部分的ide都会帮你提示,让你知道你还有什么事没有做。比如:if (order.isPaid() /TODO: 更新订单4.5 在需要留空的地方放一个空语句或注释,告述读者,你是故意的比如:if (!exists(order) ;或:if (!exists(order) /nothing to do4.6 不要再对boolean值做true fals
13、e判断比如:if (order.isPaid() = true) / Do something here不如写成:if (order.isPaid() /Do something here后者读起来就很是 if order is paid, . 要比 if orders isPaid method returns true, 更容易理解4.7 减少代码嵌套层次代码嵌套层次达3层以上时,一般人理解起来都会困难。下面的代码是一个简单的例子:public void demo(int a, int b, int c) if (a b) if (b c) doJobA(); else if (b c)
14、if (a b & b c) doJobA(); if (a b & c b) doJobB(); if (a = b & c b & a b) if (b c) doJobA(); return; doJobB() return; if (b c) if (a c) doJobC(); 利用子方法,就是将嵌套的程序提取出来放到另外的方法里。4.8 程序职责单一关注点分离是软件开发的真理。人类自所以能够完成复杂的工作,就是因为人类能够将工作分解到较小级别的任务上,在做每个任务时关注更少的东西。让程序单元的职责单一,可以使你在编写这段程序时关注更少的东西,从而降低难度,减少出错。4.9 变量的声
15、明,初始化和被使用尽量放到一起比方说如下代码:int orderNum= getOrderNum();/do something withou orderNum herecall(orderNum);上例中的注释处代表了一段和orderNum不相关的代码。orderNum的声明和初始化离被使用的地方相隔了很多行的代码,这样做不好,不如这样:/do something withou orderNum hereint orderNum= getOrderNum();call(orderNum);4.10 缩小变量的作用域能用局部变量的,不要使用实例变量,能用实例变量的,不要使用类变量。变量的生存期
16、越短,以为着它被误用的机会越小,同一时刻程序员要关注的变量的状态越少。实例变量和类变量默认都不是线程安全的,局部变量是线程安全的。比如如下代码:public class OrderPayAction private Order order; public void doAction() order = orderDao.findOrder(); doJob1(); doJob2(); private void doJob1() doSomething(order); private void doJob2() doOtherThing(order); 上例中order只不过担当了在方法间传递参
17、数之用,用下面的方法更好:public class OrderPayAction public void doAction() order = orderDao.findOrder(); doJob1(order); doJob2(order); private void doJob1(Order order) doSomething(order); private void doJob2(Order order) doOtherThing(order); 4.11 尽量不要用参数来带回方法运算结果比如:public void calculate(Order order) int result
18、 = 0; /do lots of computing and store it in the result order.setResult(result);public void action() order = orderDao.findOrder(); calculate(order); / do lots of things about order例子中calculate方法通过传入的order对象来存储结果, 不如如下写:public int calculate(Order order) int result = 0; /do lots of computing and store it in the result return result;public void action() order = orderDao.findOrder(); order.setResult(calculate(order); / do lots of things about order4.12 最后,还是要多些单元测试类,因为单元测试类可以提前发现代码中的好多问题。
copyright@ 2008-2022 冰豆网网站版权所有
经营许可证编号:鄂ICP备2022015515号-1