项目开发规范V01.docx

1、项目开发规范V01项目开发规范修订历史记录日期版本说明作者目录项目代码开发规范手册 1修订历史记录 21 项目目录规范 41.1 Java源文件目录 41.2 Web应用程序目录 41.3 Maven目录 51.4 SpringBoot目录 52 Java代码规范 52.1 命名规范 52.2 代码格式 62.3 注释 72.4 URI设计原则 73 前端代码规范 83.1 命名规范 83.2 代码规范 104 文档规范 135 其他规范 155.1 Svn源码提交 155.2 限制session的使用 155.3 限制外部包的使用 15【张三补充】 151 项目目录规范1.1 Java源文件

2、目录目录名说明src（Java源代码）|_com域名倒置|_inspur公司名|_common公用包|_util工具包|_db数据库访问类|_其他公用包|_模块名模块功能实现包|_dao数据库访问接口包 |_impl数据库访问实现类包|_service模块业务接口包 |_impl模块业务实现类包|_controller模块专用controller类包1.2 Web应用程序目录目录名说明webpage（Web页面源代码）|_images页面图片|_jsJavascript源代码|_css样式表文件|_admin系统管理功能|_模块名系统管理模块功能实现页面|_模块名业务模块功能实现页面 |_WE

3、B-INFweb.xml等文件存放目录 |_classesJava类class文件目录 *.properties | *.xml配置文件|_lib应用程序所需类包|_config系统配置信息1.3 Maven目录待补充1.4 SpringBoot目录待补充2 Java代码规范2.1 命名规范（1）package的命名由小写单词组成，例如：mon。包命名规则见目录规范（2）Class的命名Class的名字必须由大写字母开头，例如：Person（3）变量的命名变量的名字必须由小写字母开头，后面的单词用大写字母开头，例如：inputFileSize（4）静态变量的命名static final 变量的

4、名字应该都大写，并且指出完整含义，例如：MAX_UPLOAD_FILE_SIZE=1024（5）参数的命名参数的名字必须和变量的命名规范一致。使用有意义的参数命名，尽量使用和要赋值的字段一样的名字。如：setSize(int size) this.size = size;（6）数组的命名数组应该用下面的方式来命名：byte buffer;而非：byte buffer;（7）方法的命名方法的命名以小写字母开头，后面的单词用大写字母开头，例如：inputFile()2.2 代码格式（8）文件头声明源文件的头部需要一个history段，对于每次对源文件的重大改动，都需要在history段中注明。该段

5、定义在package和import之间，例如：* HISTORY* 2017/08/01 Biz 创建文件* 2007/08/02 kevin 增加XX功能*2007/08/10 ben 增加xx功能*/（9）类和方法定义，例如：public class CounterSetextends Observableimplements Cloneableprivate PortletSet getPortlets( Portlets portlets,RunData rundata,boolean application,boolean applicationsOnly )（10）HQL /SQL

6、语句代码中书写的sql语句要求sql关键字全部大写，表名和字段名小写。例如：SELECT user_id, name FROM account WHERE user_id ? AND depart = ? ORDER BY name2.3 注释（11）public 和 protected的成员变量和方法必须写javadoc注释。对于代码中的逻辑分支或循环条件需要书写注释，例如：if (some condition)/符合某个条件，应该这样处理else/否则应该那样处理2.4 URI设计原则（12）URI的末尾不要添加“/”多一个斜杠，语义完全不同，究竟是目录，还是资源，还是不确定而多做一次30

7、1跳转负面case：正面case：（13） 使用“-”提高URI的可读性目的是使得URI便于理解，用“-”来连接单词正面case：（14） 禁止在URL中使用“_”目的是提高可读性，“_”可能被文本查看器中的下划线特效遮蔽负面case：别争，看到效果就明白了（15）禁止使用大写字母RFC 3986中规定URI区分大小写 负面case：正面case：（16）不要在URI中包含扩展名应鼓励REST API客户端使用HTTP提供的格式选择机制Accept request header正面case：一个case：（17）建议URI中的名称使用复数正面case：负面case：3 前端代码规范3.1 命名

8、规范jsp与html文件名全部小写，并遵循如下的规范： a.数据/内容显示页: 名词，多个单词用下划线分隔，要求能说明显示内容的信息，为避免冲突，可加上 “_list”。 例如： new_message.html 或 my_file_list.jsp b.操作处理页 命名格式：名词_下划线_动词，例如：file_delete.jsp。 c.含frame页面 中的name属性命名的格式是xxx_xxx_xxx xxx部分用来标识当前页面隶属于整个系统中的哪一功能模块。 如：属于ebwebmail模块则写ebwebmail，其它情况依次类推。 xxx部分标识当前页面所要完成的功能。 如：完成用户登

9、录的功能则被标识为login，其它情况依次类推。 xxx部分用来用来表示页面在浏览器窗口所处的位置。 处于浏览器窗口的顶部则标识为top，其它情况依次类推。 例如：ebwebmail_inbox_top.jsp src属性相应的文件名根据情况建议在原命名规范上用下划线加上所处窗口的位置。2、javascript脚本文件命名方式： 脚本函数都以xxx_xxx的方式命名。 xxx对应页面隶属的模块。 xxx表示函数所要实现的功能(动宾结构)，多个单词用下划线连接。 例如：ebwebmail_send_mail() 模块通用的脚本函数必须集合于一个js文件中，在页面上通过形式导入。js文件名命名使用

10、模块名，例如：ebwebmail.js。 如果项目已经提供了公共js脚本，则优先使用公共js脚本中提供的函数。 所有定义方法的元素定义在中或后。3、javascript脚本内部变量与参数 单词之间用下划线分隔且全部小写，例如： var file_size。 表单name属性 统一以“form_”开头，其后加该表单所需收集的信息的作用或动作，例如：form_file_upload 或 form_send_mail。 表单elements 表单element的名称以element需收集的信息标示命名（与struts中的属性名对应），其他element单词之间使用下划线分隔且全部小写，例如： -us

11、ername为struts中的属性名username -不与struts对应表单元素名4、cookie命名 命名格式：模块名_存储信息名词(多个单词用下划线分隔) ，全部大写，例如：EBWEBMAIL_SORT_TYPE。5、window.open中name参数的命名 javascript的window.open方法中有一个name的参数，浏览器约定同样的名字的窗口只能打开一个，如果程序间名字重复将相互冲突。如果不限制打开窗口数，可以指定或“”（不是null），否则需要加上模块名，例如ebwebmail_viewmail。3.2 代码规范1、jsp/html描述注释jsp/html页面顶部必须

12、存在一个基本描述注释，包含功能描述、参数列表和历史修改信息，例如：2、jsp头格式jsp头部一般需要遵循以下格式： / jdk标准包 / java扩展包 /使用的外部库的包 /使用的项目的公共包 /使用的模块的其他包 /include其他的jsp /一般jsp都需要防止缓存2、html格式1. html头一般需要遵循以下格式：some title/some javascript注意：必须指定一个有意义的，严禁出现“Untitled”或“未命名”之类的。2. 所有html标签使用小写3. html页面一般需要设置一个背景色（一般是#FFFFFF）。html语法校验所有的jsp/html页面需要能

13、够使用DreamWeaver正确打开（即html语法正确，没有错误的标记）。注释一般不使用html注释，除非是有必要让最终用户看到的内容。对于包含JSP代码的html块，必须使用JSP注释。对于没有必要的注释，在发行版本中必须移除。form属于域的maxlength对于text类型的输入域，必须根据数据库字段的长度设置相应的maxlength，例如数据库类型是VARCHAR(64)，那么maxlength是32（因为中文浏览器对于中文也认为是一个字符）。4 文档规范1. 编写文档目前主要使用的工具是Word（项目计划文档例外，需要使用Project制作），辅助使用的工具有Visio，Power

14、Point，Excel等。2. 文档务必保持段落格式整齐，文字字体，颜色，大小统一。3. 如果需要摘引html页面中的内容，不能直接从html中粘贴过来（会在word文档中留下html格式），而必须先去除格式，例如：先粘贴到notepad中。4. 务必注意中英文标点符号，文档正文一概使用中文标点符号。5. 如果需要在文档中插图，不要使用word自带的绘图工具。可以选择使用PowerPoint或visio。使用PowerPoint，选择“插入”-“对象”-“Microsoft PowerPoint 幻灯片”。使用visio，需要另外建立visio文档，绘制完以后粘贴到word中。6. 数据建模使

15、用powerdesigner工具，文档中仅需要粘贴数据模型的逻辑视图（logical view），另外还要附上表结构描述。7. 修改他人文档务必使用修订模式，以便保留备修改的内容。使用修订模式，选择“工具”-“修订”-“突出显示修订”，勾上“编辑时标记修订”。附：一些模版Java类设计文档(class documentation)声明：描述：创建人：创建时间：属性：1. property_name声明：说明：创建人：创建时间：方法： 1. method_name声明：说明：参数：返回值：异常：创建人：创建时间：如需修改加上：修改人：修改时间：修改原因：三个描述信息注：方法声明中，如果遇到重载的

16、方法，可以使用“|”表示可以接受不同类型的参数，例如：“String value | int value”；可以使用“”表示可选的参数，例如：“Object message,Throwable t”Servlet设计(servlet document)类名 接受参数列表 描述数据表设计(data modeling)表名：some_table说明：description表结构：字段名 类型 说明5 其他规范5.1 Svn源码提交目前不限制开发工具的使用，但提交到SVN的代码必须不依赖任何IDE，必须附带上更新说明。5.2 限制session的使用在代码中使用session需要听取项目经理的意见，项目经理需要在设计文档中登记项目中所有使用到的session的名字和作用。5.3 限制外部包的使用开发员如果需要使用一个外部包需要听取项目经理的意见。在项目经理批准以前，严禁擅自使用一个外部的包。