项目开发规范（Java） rivershan（原作）

项目开发规范（Java）    rivershan（原作）
 
关键字     JAVA、代码规范
 

       前几天整理出来的一个JAVA的代码书写规范！

项目开发规范

一、目的    

　　对于代码，首要要求是它必须正确，能够按照程序员的真实思想去运行；第二个的要求是代码必须清晰易懂，使别的程序员能够容易理解代码所进行的实际工作。在软件工程领域，源程序的风格统一标志着可维护性、可读性，是软件项目的一个重要组成部分。而目前还没有成文的编码风格文档，以致于很多时候，程序员没有一个共同的标准可以遵守，编码风格各异，程序可维护性差、可读性也很差。通过建立代码编写规范，形成开发小组编码约定，提高程序的可靠性、可读性、可修改性、可维护性、可继承性和一致性，可以保证程序代码的质量，继承软件开发成果，充分利用资源，使开发人员之间的工作成果可以共享。

   本文在参考业界已有的编码风格的基础上，描述了一个基于 JBuilder 的项目风格，力求一种统一的编程风格，并从整体编码风格、代码文件风格、函数编写风格、变量风格、注释风格等几个方面进行阐述。（这些规范并不是一定要绝对遵守，但是一定要让程序有良好的可读性）

二、整体编码风格

1、缩进

   缩进建议以4个空格为单位。建议在 Tools/Editor Options 中设置 Editor 页面的Block ident为4，Tab Size 为8。预处理语句、全局数据、标题、附加说明、函数说明、标号等均顶格书写。语句块的"{"、"}"配对对齐，并与其前一行对齐，语句块类的语句缩进建议每个"{"、"}"单独占一行，便于匹对。JBuilder 中的默认方式是开始的"{"不是单独一行，建议更改成上述格式（在 Project/Default Project Properties 中设置 Code Style 中选择 Braces 为 Next line）。

2、空格

   原则上变量、类、常量数据和函数在其类型，修饰名称之间适当空格并据情况对齐。关键字原则上空一格，如：if ( ... ) 等。运算符的空格规定如下："::"、"->"、"["、"]"、"++"、"--"、"~"、"!"、"+"、"-"（指正负号）、"&"（引用）等几个运算符两边不加空格（其中单目运算符系指与操作数相连的一边），其它运算符（包括大多数二目运算符和三目运算符"?:"两边均加一空格，在作函数定义时还可据情况多空或不空格来对齐，但在函数实现时可以不用。","运算符只在其后空一格，需对齐时也可不空或多空格。不论是否有括号，对语句行后加的注释应用适当空格与语句隔开并尽可能对齐。个人认为此项可以依照个人习惯决定遵循与否。

3、对齐

   原则上关系密切的行应对齐，对齐包括类型、修饰、名称、参数等各部分对齐。另每一行的长度不应超过屏幕太多，必要时适当换行，换行时尽可能在","处或运算符处，换行后最好以运算符打头，并且以下各行均以该语句首行缩进，但该语句仍以首行的缩进为准，即如其下一行为“{”应与首行对齐。

   变量定义最好通过添加空格形成对齐，同一类型的变量最好放在一起。如下例所示：
int        Value;
int        Result;
int        Length;
DWORD      Size;
DWORD      BufSize;

个人认为此项可以依照个人习惯决定遵循与否。

4、空行

不得存在无规则的空行，比如说连续十个空行。程序文件结构各部分之间空两行，若不必要也可只空一行，各函数实现之间一般空两行，由于每个函数还要有函数说明注释，故通常只需空一行或不空，但对于没有函数说明的情况至少应再空一行。对自己写的函数，建议也加上“//------”做分隔。函数内部数据与代码之间应空至少一行，代码中适当处应以空行空开，建议在代码中出现变量声明时，在其前空一行。类中四个“p”之间至少空一行，在其中的数据与函数之间也应空行。

5、注释

注释是软件可读性的具体体现。程序注释量一般占程序编码量的20%，软件工程要求不少于20%。程序注释不能用抽象的语言，类似于"处理"、"循环"这样的计算机抽象语言，要精确表达出程序的处理说明。例如："计算净需求"、"计算第一道工序的加工工时"等。避免每行程序都使用注释，可以在一段程序的前面加一段注释，具有明确的处理逻辑。

注释必不可少，但也不应过多，不要被动的为写注释而写注释。以下是四种必要的注释：

A. 标题、附加说明。

B. 函数、类等的说明。对几乎每个函数都应有适当的说明，通常加在函数实现之前，在没有函数实现部分的情况下则加在函数原型前，其内容主要是函数的功能、目的、算法等说明，参数说明、返回值说明等，必要时还要有一些如特别的软硬件要求等说明。公用函数、公用类的声明必须由注解说明其使用方法和设计思路，当然选择恰当的命名格式能够帮助你把事情解释得更清楚。

C. 在代码不明晰或不可移植处必须有一定的说明。

D. 及少量的其它注释，如自定义变量的注释、代码书写时间等。

 注释有块注释和行注释两种，分别是指："/**/"和"//"建议对A用块注释，D用行注释，B、C则视情况而定，但应统一，至少在一个单元中B类注释形式应统一。具体对不同文件、结构的注释会在后面详细说明。

6、代码长度

对于每一个函数建议尽可能控制其代码长度为53行左右，超过53行的代码要重新考虑将其拆分为两个或两个以上的函数。函数拆分规则应该一不破坏原有算法为基础，同时拆分出来的部分应该是可以重复利用的。对于在多个模块或者窗体中都要用到的重复性代码，完全可以将起独立成为一个具备公用性质的函数，放置于一个公用模块中。

7、页宽

页宽应该设置为80字符。源代码一般不会超过这个宽度, 并导致无法完整显示, 但这一设置也可以灵活调整. 在任何情况下, 超长的语句应该在一个逗号或者一个操作符后折行. 一条语句折行后, 应该比原来的语句再缩进2个字符.

8、行数

一般的集成编程环境下，每屏大概只能显示不超过50行的程序，所以这个函数大概要5-6屏显示，在某些环境下要8屏左右才能显示完。这样一来，无论是读程序还是修改程序，都会有困难。因此建议把完成比较独立功能的程序块抽出，单独成为一个函数。把完成相同或相近功能的程序块抽出，独立为一个子函数。可以发现，越是上层的函数越简单，就是调用几个子函数，越是底层的函数完成的越是具体的工作。这是好程序的一个标志。这样，我们就可以在较上层函数里容易控制整个程序的逻辑，而在底层的函数里专注于某方面的功能的实现了。

三、代码文件风格

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

. 文件生成

对于规范的 JAVA 派生类，尽量用 JBuilder 的 Object Gallery 工具来生成文件格式，避免用手工制作的头文件/实现文件。

. package/import

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

package hotlava.net.stats;

import java.io.*;
import java.util.Observable;
import hotlava.util.Application;  

这里 java.io.* 使用来代替InputStream and OutputStream 的。

. 文件头部注释

文件头部注释主要是表明该文件的一些信息，是程序的总体说明，可以增强程序的可读性和可维护性。文件头部注释一般位于 package/imports 语句之后，Class 描述之前。要求至少写出文件名、创建者、创建时间和内容描述。JBuilder 的 Object Gallery 工具生成的代码中会在类、工程文件中等自动添加注释，我们也要添加一些注释，其格式应该尽量约束如下：

/**
* Title:  确定鼠标位置类
* Description: 确定鼠标当前在哪个作业栏位中并返回作业号
* @Copyright: Copyright (c) 2002
* @Company: HIT
* @author: rivershan
* @version: 1.0
* @time: 2002.10.30
*/

. Class

接下来的是类的注释，一般是用来解释类的。

/**
* A class representing a set of packet and byte counters
* It is observable to allow it to be watched, but only
* reports changes when the current set is complete
*/

接下来是类定义，包含了在不同的行的 extends 和 implements

public class CounterSet
 extends Observable
 implements Cloneable

.Class Fields

接下来是类的成员变量：

/**
* Packet counters
*/

protected int[] packets;

public 的成员变量必须生成文档（JavaDoc）。proceted、private和 package 定义的成员变量如果名字含义明确的话，可以没有注释。

. 存取方法

接下来是类变量的存取的方法。它只是简单的用来将类的变量赋值获取值的话，可以简单的写在一行上。（个人认为尽量分行写）

/**
* Get the counters
* @return an array containing the statistical data.  This array has been
* freshly allocated and can be modified by the caller.
*/

public int[] getPackets()
{
 return copyArray(packets, offset);
}

public int[] getBytes()
{
return copyArray(bytes, offset);
}

public int[] getPackets()
{
return packets;
}

public void setPackets(int[] packets)
{
this.packets = packets;
}

其它的方法不要写在一行上

. 构造函数

接下来是构造函数，它应该用递增的方式写（比如：参数多的写在后面）。

访问类型("public","private" 等.)和任何"static","final"或"synchronized"应该在一行中，并且方法和参数另写一行，这样可以使方法和参数更易读。

public
CounterSet(int size)
{
  this.size = size;
}

. 克隆方法

如果这个类是可以被克隆的，那么下一步就是 clone 方法：

public
Object clone()
{
try
  {
    CounterSet obj = (CounterSet)super.clone();
    obj.packets = (int[])packets.clone();
    obj.size = size;
    return obj;
  }  
  catch(CloneNotSupportedException e)
  {
   throw new InternalError("Unexpected CloneNotSUpportedException: "
         + e.getMessage());
  }
}

. 类方法

下面开始写类的方法：

/**
* Set the packet counters
* (such as when restoring from a database)
*/
protected final
void setArray(int[] r1, int[] r2, int[] r3, int[] r4)
 throws IllegalArgumentException
{
//
  // Ensure the arrays are of equal size
  //
  if (r1.length != r2.length || r1.length != r3.length || r1.length != r4.length)
 throw new IllegalArgumentException("Arrays must be of the same size");
  System.arraycopy(r1, 0, r3, 0, r1.length);
  System.arraycopy(r2, 0, r4, 0, r1.length);
}

. toString 方法

无论如何，每一个类都应该定义 toString 方法：

public
String toString()
{
String retval = "CounterSet: ";
   for (int i = 0; i < data.length(); i++)
   {
      retval += data.bytes.toString();
      retval += data.packets.toString();
   }
   return retval;
}

. main 方法

如果main(String[]) 方法已经定义了, 那么它应该写在类的底部.

四、函数编写风格

. 函数的命名

通常，函数的命名也是以能表达函数的动作意义为原则的，一般是由动词打头，然后跟上表示动作对象的名词，各单词的首字母应该大写。另外，还有一些函数命名的通用规则。如取数，则用Get打头，然后跟上要取的对象的名字；设置数，则用Set打头，然后跟上要设的对象的名字；而对象中为了响应消息进行动作的函数，可以命名为On打头，然后是相应的消息的名称；进行主动动作的函数，可以命名为Do打头，然后是相应的动作名称。类似的规则还有很多，需要程序员多读优秀的程序，逐渐积累经验，才能作出好的函数命名。

. 函数注释

系统自动生成的函数，如鼠标动作响应函数等，不必太多的注释和解释；

对于自行编写的函数，若是系统关键函数，则必须在函数实现部分的上方标明该函数的信息，格式如下：

/**
* 函数名：
* 编写者：
* 参考资料：
* 功  能：
* 输入参数：
* 输出参数：
* 备  注：
*/

希望尽量遵循以上格式。

五、符号风格

. 总体要求

对于各种符号的定义，都有一个共通点，就是应该使用有实际意义的英文单词或英文单词的缩写，不要使用简单但没有意义的字串，尽可能不使用阿拉伯数字，更切忌使用中文拼音的首字母。如这样的名称是不提倡的：Value1,Value2,Value3,Value4 …。

例如：
file(文件),code(编号),data(数据),pagepoint(页面指针), faxcode(传真号) ,address(地址),bank(开户银行),……

. 变量名称

变量命名由（前缀+修饰语）构成。现在比较流行的是一套由微软的一个匈牙利软件工程师首先使用，并且在微软推广开来，现在被称之为匈牙利命名法的命名规则。匈牙利命名法规定，使用表示标识符所对应的变量类型的英文小写缩写作为标识符的前缀，后面在使用表示变量意义的英文单词或缩写进行命名。下面是匈牙利命名法中的一些命名方式：

（1）生存期修饰：用l(local)表示局域变量，p(public)表示全局变量，s(send)表示参数变量

（2）类型修饰：用s(AnsiString)表示字符串,c(char)表示字符,n(number)数值,i(intger)表示整数,d(double)表示双精度,f(float)浮点型,b(bool)布尔型,d(date)表示日期型.

例如：
li_length表示整形的局域变量,是用来标识长度的.ls_code表示字符型的局域变量,用来标识代码.

. 控件名称

控件命名由（前缀+修饰语）构成。前缀即为控件的名称。

按钮变量  Button+Xxxxxxx    例如：ButtonSave,ButtonExit,ButtonPrint等
题标变量  Label+Xxxxxxxx    例如：LabelName,LabelSex等
数据表变量 Table+Xxxxxx      例如：TableFile,TableCount等
查询变量  Query+Xxxxxx      例如：QueryFile,QueryCeneter等
数据源变量 DataSource+Xxx      例如：DataSourceFile,DataSourceCenter等
。。。。。。。。。。。。。。。。
(注：对于与表有关的控件“修饰语”部分最好直接用表名。)

. Package 的命名

Package 的名字应该都是由一个小写单词组成。

. Class 的命名

Class 的名字必须由一个或数个能表达该类的意思的大写字母开头而其它字母都小写的单词或缩写组成，这样能使这个 Class 的名称能更容易被理解。

. Class 变量的命名

变量的名字必须用一个小写字母开头。后面的单词用大写字母开头。对于类的成员变量，在对其标识符命名时，要加上代表member（成员）的前缀m_。例如一个标识符为m_dwFlag，则它表示的变量是一个类型为双字的成员变量，它是代表一个标志。

. Static Final 变量的命名

Static Final 变量的名字应该都大写，并且指出完整含义。

. 参数的命名

参数的名字必须和变量的命名规范一致。

. 数组的命名

数组应该总是用下面的方式来命名：
byte[] buffer;  

而不是：
byte buffer[];

. 方法的参数

使用有意义的参数命名，如果可能的话，使用和要赋值的字段一样的名字：

SetCounter(int size)
{
this.size = size;
}

. 神秘的数

首先要说什么是神秘的数。我们在程序里经常会用到一些量，它是有特定的含义的。例如，现在我们写一个薪金统计程序，公司员工有50人，我们在程序里就会用50这个数去进行各种各样的运算。在这里，50就是"神秘的数"。为什么称它为神秘呢？因为别的程序员在程序里看到50这个数，不知道它的含义，只能靠猜了。

在程序里出现"神秘的数"会降低程序的可读性，应该尽量避免。避免的方法是把神秘的数定义为一个常量。注意这个常量的命名应该能表达该数的意义，并且应该全部大写，以与对应于变量的标识符区别开来。例如上面50这个数，我们可以定义为一个名为NUMOFEMPLOYEES的常量来代替。这样，别的程序员在读程序的时候就可以容易理解了。

六、程序编写风格

. exit()

exit 除了在 main 中可以被调用外，其他的地方不应该调用。因为这样做不给任何代码代码机会来截获退出。一个类似后台服务地程序不应该因为某一个库模块决定了要退出就退出。

. 异常

申明的错误应该抛出一个RuntimeException或者派生的异常。
顶层的main()函数应该截获所有的异常，并且打印（或者记录在日志中）在屏幕上。

. 垃圾收集

JAVA使用成熟的后台垃圾收集技术来代替引用计数。但是这样会导致一个问题：你必须在使用完对象的实例以后进行清场工作。比如一个prel的程序员可能这么写：

...
{
 FileOutputStream fos = new FileOutputStream(projectFile);
 project.save(fos, "IDE Project File");
}
...

除非输出流一出作用域就关闭，非引用计数的程序语言，比如JAVA，是不能自动完成变量的清场工作的。必须象下面一样写：

FileOutputStream fos = new FileOutputStream(projectFile);
project.save(fos, "IDE Project File");
fos.close();

. Clone

下面是一种有用的方法：
implements Cloneable

public
Object clone()
{
try
{
 ThisClass obj = (ThisClass)super.clone();
 obj.field1 = (int[])field1.clone();
 obj.field2 = field2;
 return obj;
}
catch(CloneNotSupportedException e)
{
 throw new InternalError("Unexpected CloneNotSUpportedException: " + e.getMessage());
}
}

. final 类

绝对不要因为性能的原因将类定义为 final 的（除非程序的框架要求）
如果一个类还没有准备好被继承，最好在类文档中注明，而不要将她定义为 final 的。这是因为没有人可以保证会不会由于什么原因需要继承她。

. 访问类的成员变量

大部分的类成员变量应该定义为 protected 的来防止继承类使用他们。
注意，要用"int[] packets"，而不是"int packets[]"，后一种永远也不要用。

public void setPackets(int[] packets)
{
this.packets = packets;
}
CounterSet(int size)
{
this.size = size;
}

. byte 数组转换到 characters

为了将 byte 数组转换到 characters，你可以这么做：

"Hello world!".getBytes();

. Utility 类

Utility 类（仅仅提供方法的类）应该被申明为抽象的来防止被继承或被初始化。

. 初始化

下面的代码是一种很好的初始化数组的方法：

objectArguments = new Object[]
{
arguments
};

. 枚举类型

JAVA 对枚举的支持不好，但是下面的代码是一种很有用的模板：

class Colour
{
  public static final Colour BLACK = new Colour(0, 0, 0);
  public static final Colour RED = new Colour(0xFF, 0, 0);
  public static final Colour GREEN = new Colour(0, 0xFF, 0);
  public static final Colour BLUE = new Colour(0, 0, 0xFF);
  public static final Colour WHITE = new Colour(0xFF, 0xFF, 0xFF);
}

这种技术实现了RED, GREEN, BLUE 等可以象其他语言的枚举类型一样使用的常量。 他们可以用 '==' 操作符来比较。
但是这样使用有一个缺陷：如果一个用户用这样的方法来创建颜色 BLACK

new Colour(0,0,0)

那么这就是另外一个对象，'=='操作符就会产生错误。她的 equal() 方法仍然有效。由于这个原因，这个技术的缺陷最好注明在文档中，或者只在自己的包中使用。

. 混合使用 AWT 和 Swing 组件

如果要将 AWT 组件和 Swing 组件混合起来使用的话，请小心使用。实际上，尽量不要将他们混合起来使用。

. 滚动的 AWT 组件

AWT 组件绝对不要用 JscrollPane 类来实现滚动。滚动 AWT 组件的时候一定要用 AWT ScrollPane 组件来实现。

. 避免在 InternalFrame 组件中使用 AWT 组件

尽量不要这么做，要不然会出现不可预料的后果。

. Z-Order 问题

AWT 组件总是显示在 Swing 组件之上。当使用包含 AWT 组件的 POP-UP 菜单的时候要小心，尽量不要这样使用。

八、性能

在写代码的时候，从头至尾都应该考虑性能问题。这不是说时间都应该浪费在优化代码上，而是我们时刻应该提醒自己要注意代码的效率。比如：如果没有时间来实现一个高效的算法，那么我们应该在文档中记录下来，以便在以后有空的时候再来实现她。

不是所有的人都同意在写代码的时候应该优化性能这个观点的，他们认为性能优化的问题应该在项目的后期再去考虑，也就是在程序的轮廓已经实现了以后。

. 不必要的对象构造

不要在循环中构造和释放对象

. 使用 StringBuffer 对象

在处理 String 的时候要尽量使用 StringBuffer 类，StringBuffer 类是构成 String 类的基础。String 类将 StringBuffer 类封装了起来，（以花费更多时间为代价）为开发人员提供了一个安全的接口。当我们在构造字符串的时候，我们应该用 StringBuffer 来实现大部分的工作，当工作完成后将 StringBuffer 对象再转换为需要的 String 对象。比如：如果有一个字符串必须不断地在其后添加许多字符来完成构造，那么我们应该使用 StringBuffer 对象和她的 append() 方法。如果我们用 String 对象代替 StringBuffer 对象的话，会花费许多不必要的创建和释放对象的 CPU 时间。

. 避免太多的使用 synchronized 关键字

避免不必要的使用关键字 synchronized，应该在必要的时候再使用她，这是一个避免死锁的好方法。

                                                                                 rivershan 原创于2002.11.5