项目编码规范

项目编码规范

（一）命名规范

Java包、类的命名应尽量采用完整的英文描述符，一般采用小写英文字母，但类名、接口名以及任何非初始单词的第一个字母要大写，不能用完整英文描述的，应以该英文单词的前四个字母或能代表单词意思的缩写代替。具体如下：

（1）尽量使用完整的英文描述符；

（2）采用合适于相关领域的术语

（3）采用大小写混合使名字可读

（4）尽量少用缩写，确有需要的，要能表达其意义；

（5）避免使用长的名字（小于15个字母）

（6）避免使用类似的名字，或者是大小写不同的名字；

（7）避免使用下划线（除静态常量等）；

举例如下：

包(packge) 采用完整的英文描述符，应该都是由小写字母组成。对于全局包，将你的internet域名反转并接上包名。如：com.boyi.eim,com.boyi.oa.web 类(Class) 采用完整的英文描述符，所有单词的第一个字母大写。如：User,StuManager

接口(interface) 采用完整的英文描述符说明接口封装,所有单词第一个字母大写。名字后面加上后缀Dao，实体类实现接口加上后缀Impl

类变量：采用完整的英文描述符，第一个字母小写，后所有单词的第一个字母大写。如：userName

参数：同上

获取成员函数:封装字段，被访问时调用get set方法

普通成员函数：采用完整的英文描述符，第一个字母小写，后所有单词的第一个字母大写。

静态常量字段：全部采用大写字母，单词之间用下划线分隔。

循环计数器：通常采用字母I,j,k……………..

数组：采用完整的英文描述符，第一个字母小写，后所有单词的第一个字母大写

（二）代码注释

良好的注释习惯对于一支程序来说，是其易于解读的关键。也就是说，如果另一个编程人员从未见过这段代码，要在合理的时间内理解代码，需要知道哪些信息。并以此作为注释的依据。因此对于注释来说，需要注意以下几点：

（1）注释应该增加代码的清晰度；

（2）保持注释的简洁；

（3）在写代码之前写注释

（4）注释出为什么做了一些事，而不仅仅是做了什么

使用代码注释的目的:

（1）文字说明代码的作用(即为什么要用编写该代码,而不是如何编写);

（2）确指出该代码的编写思路和逻辑方法;

（3）人们注意到代码中的重要转折点;

（4）使代码的阅读者不必在他们的头脑中仿真运行代码的执行方法.

代码注释原则：

1. 用文字说明代码的作用:简单的重复代码做写什么,这样的注释几乎不能给注释增加什么信息.如果你使用好的命名方法来创建直观明

了的代码那么这些类型的注释绝对增加不了什么信息.

2. 如果你想违背好的编程原则,请说明为什么：有的时候你可能需要违背好的编程原则，或者使用了某些不正规的方法，.遇到这种情况

时,请用内部注释来说明你在做什么和为什么要这样做。技巧性特别高的代码段，一定要加详细的注释，不要让其他开发人员花很长时间来研究一个高技巧但不易理解的程序段。

3. 用注释来说明何时可能出错和为什么出错

4. 在编写代码前进行注释：给代码加注释的方法之一是在编写一个方法前首先写上注释.如果你愿意,可以编写完整句子的注释或伪代码.

一旦你用注释对代码进行了概述,就可以在注释之间编写代码.

5. 在要注释的代码前书写注释：注释一定出现在要注释的程序段前，不要在某段程序后书写对这段程序的注释，先看到注释对程序的理解会有一定帮助。如果有可能，请在注释行与上面代码间加一空行。

6. 纯色字符注释行只用于主要注释：注释中要分隔时，请使用一行空注释行来完成，不要使用纯色字符，以保持版面的整洁、清晰。

7. 避免形成注释框：用星号围成的注释框，右边的星号看起来很好,但它们给注释增加了任何信息吗?实际上这会给编写或编辑注释的人增加许多工作。

8. 增强注释的可读性，注释是供人阅读的，而不是让计算机阅读的。

1) 使用完整的语句。虽然不必将注释分成段落（最好也不要分成段落），但你应尽量将注释写成完整的句子。

2) 避免使用缩写。缩写常使注释更难阅读，人们常用不同的方法对相同的单词进行缩写，这会造成许多混乱，如果必须对词汇缩写，必须做到统一。

3) 将整个单词大写，以突出它们的重要性。若要使人们注意注释中的一个或多个单词，请全部使用大写字母。

9. 对注释进行缩进，使之与后随的语句对齐。注释通常位于它们要说明的代码的前面。为了从视觉上突出注释与它的代码之间的关系，请将注释缩进，使之与代码处于同一个层次上。

10. 为每个方法赋予一个注释标头：每个方法都应有一个注释标头。方法的注释标头可包含多个文字项，比如输入参数、返回值、原始作者、最后编辑该方法的程序员、上次修改日期、版权信息。

11. 当行尾注释用在上面这种代码段结构中时，它们会使代码更难阅读。使用多个行尾注释时（比如用于方法顶部的多个变量说明），应使它们互相对齐。这可使它们稍容易阅读一些。

12. 何时书写注释

1) 请在每个if语句的前面加上注释。

2) 在每个switch语句的前面加上注释。与if语句一样，switch语句用于评估对程序执行产生影响的表达式。

3) 在每个循环的前面加上注释。每个循环都有它的作用，许多情况下这个作用不清楚直观。

注释分类举例如下：

文档注释在紧靠接口、类、成员函数和字段声明的前面注释它们。例如：/** 客户：客户是我们将服务和产品卖给的人或机构。*/ 常规注释常规注释去掉不再使用但你仍想保留的代码。仍想保留是因为用户万一会改变想法，或者在调试过程中想让它暂时失效。/* 这部分代码因为已有替代代码，于2007-10-6注释。如果一年之后还未使用，将其删除。. . . （源代码）*/

单行注释在成员函数内采用单行注释，来说明业务逻辑、代码段和暂时变量的声明。注释符"//"后必须紧跟一个空格，然后才是注释信息。例如：// 遵照Sarek 的规定，//于2007-10-6修改。

(三）文件样式

所有的Java(*.java) 文件都必须遵守如下的样式规则：

（1）版权信息

版权信息或者开发者信息必须在java 文件的开头，比如：

/** * Copyright ? 2007 Beijing Boyi software Co. Ltd. * All right reserved. */

其他不需要出现在javadoc 的信息也可以包含在这里。

（2）包/引入（Package/Imports）

package 行要在import 行之前，import 中标准的包名要在本地的包名之前，而且按照字母顺序排列。如果import 行中包含了同一个包中的不同子目录，则应该用* 来处理。举例如下：

package .stats;

import java.io.*;

import java.util.Observable;

import hotlava.util.Application;

这里java.io.* 是用来代替InputStream、OutputStream 的。

（3）类（Class）

类的注释，一般是用来解释类的。例如：