java编码规范文档

Java代码规范1.标识符命名规范1.1简洁简洁是指，在统一和达意的前提下，用尽量少的标识符。如果不能达意，宁愿不要简洁。比如：theOrderNameOfTheTargetSupplierWhichIsTransfered太长，transferedTargetSupplierOrderName则较好，但是transTgtSplOrdNm就不好了。省略元音的缩写方式不要使用，我们的英语往往还没有好到看得懂奇怪的缩写。1.2英文vs拼音尽量使用通俗易懂的英文单词，如果不会可以向队友求助，实在不行则使用汉语拼音，避免拼音与英文混用。比如表示归档，用archive比较好,用pigeonhole则不好，用guiDang尚可接受。1.3包名使用小写字母如com.xxx.settlment，不要com.xxx.Settlement单词间不要用字符隔开，比如com.xxx.settlment.jsfutil，而不要com.xxx.settlement.jsf_util1.4类名1.4.1首字母大写类名要首字母大写，比如SupplierService,PaymentOrderAction；不要supplierService,paymentOrderAction.1.5方法名首字母小写，如addOrder()不要AddOrder()动词在前，如addOrder()，不要orderAdd()名称不要太长动词前缀往往表达特定的含义，如下表：前缀名意义举例create创建createOrder()delete删除deleteOrder()add创建，暗示新创建的对象属于某个集合addPaidOrder()remove删除removeOrder()init或则initialize初始化，暗示会做些诸如获取资源等特殊动作initializeObjectPooldestroy销毁，暗示会做些诸如释放资源的特殊动作destroyObjectPoolopen打开openConnection()close关闭closeConnection()read读取readUserName()write写入writeUserName()get获得getName()set设置setName()prepare准备prepareOrderList()copy复制copyCustomerList()modity修改modifyActualTotalAmount()calculate数值计算calculateCommission()do执行某个过程或流程doOrderCancelJob()dispatch判断程序流程转向dispatchUserRequest()start开始startOrderProcessing()stop结束stopOrderProcessing()send发送某个消息或事件sendOrderPaidMessage()receive接受消息或时间receiveOrderPaidMessgae()respond响应用户动作responseOrderListItemClicked()find查找对象findNewSupplier()update更新对象updateCommission()find方法在业务层尽量表达业务含义，比如findUnsettledOrders()，查询未结算订单，而不要findOrdersByStatus()。数据访问层，find,update等方法可以表达要执行的sql，比如findByStatusAndSupplierIdOrderByName(Status.PAID,345)1.6域（field）名1.6.1静态常量全大写用下划线分割，如publicstaticfindStringORDER_PAID_EVENT=“ORDER_PAID_EVENT”;1.6.2枚举全大写，用下划线分割，如publicenumEvents{ORDER_PAID,ORDER_CREATED}1.6.3其他首字母小写，骆驼法则，如：publicStringorderName;1.7局部变量名参数和局部变量名首字母小写，骆驼法则。尽量不要和域冲突，尽量表达这个变量在方法中的意义。2.代码格式用空格字符缩进源代码，不要用tab，每个缩进4个空格。2.1包的导入删除不用的导入，尽量不要使用整个包的导入。在eclipse下经常使用快捷键ctrl+shift+o修正导入。2.2域格式每行只能声明一个域。域的声明用空行隔开。2.3代码块格式2.4.1缩进风格大括号的开始在代码块开始的行尾，闭合在和代码块同一缩进的行首，例如：packagecom.test;publicclassTestStyleextendsSomeClassimplementsAppleInter,BananaInter{publicstaticfinalStringTHIS_IS_CONST=CONSTVALUE;privatestaticvoidmain(String[]args){intlocalVariable=0;}publicvoidcompute(Stringarg){if(arg.length()0){System.out.println(arg);}for(inti=0;i10;i++){System.out.println(arg);}while(condition){}do{otherMethod();}while(condition);switch(i){case0:callFunction();break;case1:callFunctionb();break;default:break;}}}2.4.2空格的使用2.4.2.1表示分割时用一个空格不能这样：if(ab){//dosomethinghere};2.4.2.2二元三元运算符两边用一个空格隔开如下：a+b=c;b-d=e;returna==b?1:0;不能如下：a+b=c;b-d=e;returna==b?1:0;2.4.2.3逗号语句后如不换行，紧跟一个空格如下：call(a,b,c);不能如下：call(a,b,c);2.4.3空行的使用空行可以表达代码在语义上的分割，注释的作用范围，等等。将类似操作，或一组操作放在一起不用空行隔开，而用空行隔开不同组的代码，如图：order=orderDao.findOrderById(id);//updatepropertiesorder.setUserName(userName);order.setPrice(456);order.setStatus(PAID);orderService.updateTotalAmount(order);session.saveOrUpdate(order);上例中的空行，使注释的作用域很明显.连续两行的空行代表更大的语义分割。方法之间用空行分割域之间用空行分割超过十行的代码如果还不用空行分割，就会增加阅读困难3注释规范3.1注释vs代码注释宜少二精，不宜多而滥，更不能误导命名达意，结构清晰，类和方法等责任明确，往往不需要，或者只需要很少注释，就可以让人读懂；相反，代码混乱，再多的注释都不能弥补。所以，应当先在代码本身下功夫。不能正确表达代码意义的注释，只会损害代码的可读性。过于详细的注释，对显而易见的代码添加的注释，罗嗦的注释，还不如不写。注释要和代码同步，过多的注释会成为开发的负担注释不是用来管理代码版本的，如果有代码不要了，直接删除，svn会有记录的，不要注释掉，否则以后没人知道那段注释掉的代码该不该删除。3.2JavaDoc表明类、域和方法等的意义和用法等的注释，要以javadoc的方式来写。JavaDoc是个类的使用者来看的，主要介绍是什么，怎么用等信息。凡是类的使用者需要知道，都要用JavaDoc来写。非JavaDoc的注释，往往是个代码的维护者看的，着重告述读者为什么这样写，如何修改，注意什么问题等。如下：/***Thisisaclasscomment*/publicclassTestClass{/***Thisisafieldcomment*/publicStringname;/***Thisisamethodcomment*/publicvoidcall(){}}3.3块级别注释3.3.1块级别注释，单行时用//,多行时用/*..*/。3.3.2较短的代码块用空行表示注释作用域3.3.3较长的代码块要用/*------start:------*/和/*--------end:-------*/包围如：/*----------start:订单处理-------*///取得daoOrderDaodao=Factory.getDao(OrderDao);/*查询订单*/Orderorder=dao.findById(456);//更新订单order.setUserName(uu);order.setPassword(pass);order.setPrice(ddd);orderDao.save(order);/*----------end:订单处理-------*/3.3.4可以考虑使用大括号来表示注释范围使用大括号表示注释作用范围的例子：/*----------订单处理-------*/{//取得daoOrderDaodao=Factory.getDao(OrderDao);/*查询订单*/Orderorder=dao.findById(456);//更新订单order.setUserName(uu);order.setPassword(pass);order.setPrice(ddd);orderDao.save(order);}3.4行内注释行内注释用//写在行尾4最佳实践和禁忌4.1每次保存的时候，都让你的代码是最美的程序员都是懒惰的，不要想着等我完成了功能，再来优化代码的格式和结构，等真的把功能完成，很少有人会再愿意回头调整代码。4.2使用log而不是System.out.println()log可以设定级别，可以控制输出到哪里，容易区分是在代码的什么地方打印的，而System.out.print则不行。而且，System.out.print的速度很慢。所以，除非是有意的，否则，都要用log。至少在提交到svn之前把System.out.print换成log。4.3每个ifwhilefor等语句，都不要省略大括号{}看下面的代码：if(ab)a++;如果在以后维护的时候，需要在ab时，把b++，一步小心就会写成：if(ab)a++;b++;这样就错了，因为无论a和b是什么关系，b++都会执行。如果一开始就这样写：if(ab){a++;}相信没有哪个笨蛋会把b++添加错的。而且，这个大括号使作用范围更明显，尤其是后面那行很长要折行时。4.4善用TODO:在代码中加入//TODO:，大部分的ide都会帮你提示，让你知道你还有什么事没有做。比如：if(order.isPaid()){//TODO:更新订单}4.5在需要留空的地方放一个空语句或注释，告述读者，你是故意的比如：if(!exists(order)){;}或：if(!exists(order)){//nothingtodo}4.6不要再对boolean值做truefalse判断比如：if(order.isPaid()==true){//Dosomethinghere}不如写成：if(order.isPaid()){//Dosomethinghere}后者读起来就很是iforderispaid,….要比iforder’sisPaidmethodreturnstrue,…更容易理解4.7减少代码嵌套层次代码嵌套层次达3层以上时，一般人理解起来都会困难。下面的代码是一个简单的例子：publicvoiddemo(inta,intb,intc){if(ab){if(bc){doJobA();}elseif(bc){