软件外包公司开发规范

XX开发规范目录前言2一、编程规约..................................................3(一)命名规约..................................................3(二)格式规约..................................................5(三)注解规约..................................................7(四)其它......................................................7二、异常日志..................................................8(一)异常处理..................................................8(二)日志规约..................................................9三、工程规约..................................................9(一)应用分层..................................................9四、安全规约.................................................10附1：版本历史...............................................11附2：常用单词对照表.........................................11前言《XX开发规范手册》是公司技术团队的集体经验总结,现代软件行业的高速发展对开发者的综合素质要求越来越高,因为不仅是编程知识点,其它维度的知识点也会影响到软件的最终交付质量。比如:数据库的表结构和索引设计缺陷可能带来软件上的架构缺陷或性能风险;工程结构混乱导致后续维护艰难;没有鉴权的漏洞代码被黑客攻击等等。所以本手册以XX开发者为中心视角,划分为编程规约、异常日志规约、MySQL规约、工程规约、安全规约五大块,再根据内容特征,细分成若干二级子目录。根据约束力强弱及故障敏感性,规约依次分为强制、推荐、参考三大类。对于规约条目的延伸信息中,“说明”对内容做了引申和解释;“正例”倡什么样的编码和实现方式;“反例”说明需要防的雷区,以及真实的错误案例。本手册的愿景是码出质量、码出高效。代码的字里行间流淌的是软件生命中的血液,质量的升是尽可能少踩坑,杜绝踩重复的坑,切实升质量意识。另外,现代软件架构都需要协同开发完成,高效协作即降低协同成本,升沟通效率,所谓无规矩不成方圆,无规范不能协作。众所周知,制订交通法规表面上是要限制行车权,实际上是保障公众的人身安全。试想如果没有限速,没有红绿灯,谁还敢上路行驶。对软件来说,适当的规范和标准绝不是消灭代码内容的创造性、优雅性,而是限制过度个性化,以一种普遍认可的统一方式一起做事,升协作效率。编程规约(一)命名规约1.【强制】代码中的命名均不能以下划线或美元符号开始,也不能以下划线或美元符号结束。反例:_name/__name/$Object/name_/name$/Object$2.【强制】代码中的命名严禁使用拼音与英文混合的方式,更不允许直接使用中文的方式。反例:DaZhePromotion[打折]/getPingfenByName()[评分]/int某变量=3正例:alibaba/taobao/youku/hangzhou等国际通用的名称,可视同英文。3.【强制】类名使用UpperCamelCase风格,必须遵从驼峰形式。正例：MemberListManager。4.【强制】方法名、参数名、成员变量、局部变量都统一使用lowerCamelCase风格,必须遵从驼峰形式。正例:localValue/getHttpMessage()/inputUserId5.【强制】常量命名全部大写,单词间用下划线隔开,力求语义表达完整清楚,不要嫌名字长。正例:MAX_STOCK_COUNT反例:MAX_COUNT6.【强制】抽象类命名使用Abstract或Base开头;异常类命名使用Exception结尾;测试类命名以它要测试的类的名称开始,以Test结尾。7.【强制】中括号是数组类型的一部分,数组定义如下:String[]args;反例:使用Stringargs[]的方式来定义。8.【强制】包名统一使用小写,点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用单数形式,但是类名如果有复数含义,类名可以使用复数形式。正例:应用工具类包名为com.alibaba.open.util、类名为MessageUtils(此规则参考spring的框架结构)9.【强制】杜绝完全不规范的缩写,避免望文不知义。反例:AbstractClass“缩写”命名成AbsClass;condition“缩写”命名成condi,此类随意缩写严重降低了代码的可阅读性。10.【强制】对于Service和DAO类,基于SOA的理念,暴露出来的服务一定是接口,内部的实现类与接口用I的前缀区别。正例:MemberManager实现IMemberManager接口。11.【强制】Controller类为区分前台商城和平台管理调用的不同，前台商城需要以ApiController结尾，平台管理以Controller结尾。正例：前台商城MemberApiController，平台管理MemberController。12.【强制】标签类，全部以Tag结尾。正例：MemberListTag。13.【强制】组件类，全部以Component结尾正例：MemberComponent。14.【强制】插件类，全部以Plugin结尾正例：MemberPointPlugin。15.【强制】Controller类中的方法，下面提供通用的方法名，如其他业务，请看10标准。16.【强制】Controller类的RequestMapping的路径格式。基本原则：将驼峰命名改为以中横线连接，将驼峰的大写母小写，注意不能以下划线连接，如listJson，则访问路径为：list-json。为区分前台商城和平台后台的区别正例：前台商城路径规范：/api/应用名路径/业务名/方法名.do正例：平台后台路径规范：/应用名路径/admin/业务名/方法名.doadd到添加页edit到修改页saveAdd保存添加saveEdit保存修改delete删除list到列表页listJson列表的json17.【强制】Controller类中方法的RequestMapping的路径格式。基本原则：将驼峰命名改为以中横线连接，将驼峰的大写母小写，注意不能以下划线连接。正例：如方法名为getMember，@RequestMapping路径则为get-member。18.【强制】各层命名规约a)Service/DAO层方法命名规约1)获取单个对象的方法用get做前缀。2)获取多个对象的方法用list做前缀。3)获取统计值的方法用count做前缀。4)插入的方法用save(推荐)或insert做前缀。5)删除的方法用remove(推荐)或delete做前缀。6)修改的方法用update做前缀。(二)格式规约1.【强制】大括号的使用约定。如果是大括号内为空,则简洁地写成{}即可,不需要换行;如果是非空代码块则:1)左大括号前不换行。2)左大括号后换行。3)右大括号前换行。4)右大括号后还有else等代码则不换行;表示终止的右大括号后必须换行。2.【强制】左小括号和右边相邻字符之间不出现空格;同样,右小括号和左边相邻字符之间也不出现空格。详见第5条下方正例提示。3.【强制】if/for/while/switch/do等保留字与小括号之间都必须加空格。4.【强制】任何运算符左右必须加一个空格。说明:运算符包括赋值运算符=、逻辑运算符&&、加减乘除符号、三目运算符等。5.【强制】缩进采用tab字符，禁止使用空格。正例:(涉及1-5点)publicstaticvoidmain(String[]args){//缩进1个tabStringsay=hello;//运算符的左右必须有一个空格intflag=0;//关键词if与括号之间必须有一个空格,括号内的f与左括号,0与右括号不需要空格if(flag==0){System.out.println(say);}//左大括号前加空格且不换行;左大括号后换行if(flag==1){System.out.println(world);//右大括号前换行,右大括号后有else,不用换行}else{System.out.println(ok);//在右大括号后直接结束,则必须换行}}6.【强制】单行字符数限制不超过120个,超出需要换行,换行时遵循如下原则:1)第二行相对第一行缩进1个TAB,从第三行开始,不再继续缩进,参考示例。2)运算符与下文一起换行。3)方法调用的点符号与下文一起换行。4)在多个参数超长,逗号后进行换行。5)在括号前不要换行,见反例。正例:StringBuffersb=newStringBuffer();//超过120个字符的情况下,换行缩进1个TAB,并且方法前的点符号一起换行sb.append(zi).append(xin)....append(huang)....append(huang)....append(huang);反例:StringBuffersb=newStringBuffer();//超过120个字符的情况下,不要在括号前换行sb.append(zi).append(xin)...append(huang);//参数很多的方法调用可能超过120个字符,不要在逗号前换行method(args1,args2,args3,...,argsX);7.【强制】方法参数在定义和传入时,多个参数逗号后边必须加空格。正例：下例中实参的a,后边必须要有一个空格。method(a,b,c);(三)注解规约1.【强制】类、类属性、类方法的注释必须使用Javadoc规范,使用/**内容*/格式,不得使用//xxx方式。说明：在IDE编辑窗口中,Javadoc方式会提示相关注释,生成Javadoc可以正确输出相应注释;在IDE中,工程调用方法时,不进入方法即可悬浮提示方法、参数、返回值的意义,提高阅读效率。2.【强制】所有的抽象方法(包括接口中的方法)必须要用Javadoc注释、除了返回值、参数、异常说明外,还必须指出该方法做什么事情,实现什么功能。说明：对子类的实现要求,或者调用注意事项,请一并说明。3.【强制】所有的类都必须添加创建者和创建日期。4.【强制】方法内部单行注释,在被注释语句上方另起一行,使用//注释。方法内部多行注释使用/**/注释，注意与代码对齐。5.【强制】所有的枚举类型字段必须要有注释,说明每个数据项的用途。6.【推荐】与其“半吊子”英文来注释,不如用中文注释把问题说清楚。专有名词与关键字保持英文原文即可。反例:“TCP连接超时”解释成“传输控制协议连接超时”,理解反而费脑筋。7.【推荐】代码修改的同时,注释也要进行相应的修改,尤其是参数、返回值、异常、核心逻辑等的修改。说明：代码与注释更新不同步,就像路网与导航软件更新不同步一样,如果导航软件严重滞后,就失去了导航的意义。(四)其它1.【强制】SVN目录规范，两个主目录。产品：/product，项目：/project若有新产品或者新项目则在对应的主目录下创建子目录。每个产品或项目结构的规范：+trunk/+branches/+dev_1.0+tags/+release_1.0说明；trunk：主开发分支：正在开发中的主分支branches:一些特殊开发需要的分支，和主分支并行开发用，命名规