Java编码规范 二

IV.   命名规范
A.   规则
1. 包名采用域后缀倒置的加上自定义的包名，采用小写字母。在部门内部应该规划好包名的范围，防止产生冲突。部门内部产品使用部门的名称加上模块名称。产品线的产品使用产品的名称加上模块的名称。
格式：
com.公司名.产品名.模块名称
com.公司名.部门名称. 项目名称
示例：
融合WEBSMAP包名  com.公司名.iin.websmap
通用消息转发包名      com.公司名.insa2.msgtrans

2. 类名和接口使用类意义完整的英文描述，每个英文单词的首字母使用大写、其余字母使用小写的大小写混合法。
示例：OrderInformation, CustomerList, LogManager, LogConfig, SmpTransaction

3. 方法名使用类意义完整的英文描述：第一个单词的字母使用小写、剩余单词首字母大写其余字母小写的大小写混合法。
示例：
private void calculateRate();
public void addNewOrder();

4. 方法中，存取属性的方法采用setter 和 getter方法，动作方法采用动词和动宾结构。
格式：
get + 非布尔属性名()
is + 布尔属性名()
set + 属性名()
动词()
动词 + 宾语()
示例：
public String getType();
public boolean isFinished();
public void setVisible(boolean);
public void show();
public void addKeyListener(Listener);

5. 属性名使用意义完整的英文描述：第一个单词的字母使用小写、剩余单词首字母大写其余字母小写的大小写混合法。属性名不能与方法名相同。
示例：
private customerName;
private orderNumber;
private smpSession;

6. 常量名使用全大写的英文描述，英文单词之间用下划线分隔开，并且使用 final static 修饰。
示例：
public final static int MAX_VALUE = 1000;
public final static String DEFAULT_START_DATE = "2001-12-08";

7. 属性名可以和公有方法参数相同，不能和局部变量相同，引用非静态成员变量时使用 this 引用，引用静态成员变量时使用类名引用。
示例：
public class Person
{
    private String name;
    private static List properties;
  
    public void setName (String name)
    {
        this.name = name;
    }
   
    public void setProperties (List properties)
    {
        Person.properties = properties;
    }

B. 建议
1. 常用组件类的命名以组件名加上组件类型名结尾。
示例：
Application 类型的，命名以App 结尾——MainApp
Frame 类型的，命名以Frame 结尾——TopoFrame
Panel 类型的，建议命名以Panel 结尾——CreateCircuitPanel
Bean 类型的，建议命名以Bean 结尾——DataAccessBean
EJB 类型的，建议命名以EJB 结尾——DBProxyEJB
Applet 类型的，建议命名以Applet 结尾——PictureShowApplet

2. 如果函数名超过15 个字母，可采用以去掉元音字母的方法或者以行业内约定俗成的缩写方式缩写函数名。
示例：getCustomerInformation()  改为  getCustomerInfo()

3. 准确地确定成员函数的存取控制符号，不是必须使用 public 属性的，请使用 protected，不是必须使用 protected, 请使用 private。
示例： protected void setUserName(), private void  calculateRate()

4. 含有集合意义的属性命名，尽量包含其复数的意义。
示例：customers,  orderItems


 
V.   编码规范
A. 规则
1. *明确方法功能，精确（而不是近似）地实现方法设计。一个函数仅完成一件功能，即使简单功能也应该编写方法实现。
说明：虽然为仅用一两行就可完成的功能去编方法好象没有必要，但用方法可使功能明确化，增加程序可读性，亦可方便维护、测试。

2. 应明确规定对接口方法参数的合法性检查应由方法的调用者负责还是由接口方法本身负责，缺省是由方法调用者负责。
说明：对于模块间接口方法的参数的合法性检查这一问题，往往有两个极端现象，即：要么是调用者和被调用者对参数均不作合法性检查，结果就遗漏了合法性检查这一必要的处理过程，造成问题隐患；要么就是调用者和被调用者均对参数进行合法性检查，这种情况虽不会造成问题，但产生了冗余代码，降低了效率。

3. 明确类的功能，精确（而不是近似）地实现类的设计。一个类仅实现一组相近的功能。
说明：划分类的时候，应该尽量把逻辑处理、数据和显示分离，实现类功能的单一性。
示例：
数据类不能包含数据处理的逻辑。
通信类不能包含显示处理的逻辑。

4. 所有的数据类必须重载toString() 方法，返回该类有意义的内容。？？？？？？？？？
说明： 父类如果实现了比较合理的toString() ，子类可以继承不必再重写。
示例：/
public TopoNode
{
      private String nodeName;

      public String toString()
      {
               return "NodeName : " + nodeName;
      }
}

5. 数据库操作、IO操作等需要使用结束close()的对象必须在try -catch-finally 的finally中close()。
示例：
try
{
    // ... ...
}
catch(IOException ioe)
{
     //... ...
}
finally
{
     try
     {
          out.close();
     }
     catch (IOException ioe)
    {
         //... ...
    }
}

6. 异常捕获后，如果不对该异常进行处理，则应该纪录日志或者ex.printStackTrace() 。
说明：若有特殊原因必须用注释加以说明。
示例：
try
{
    //.... ...
}
catch (IOException ioe)
{
    ioe.printStackTrace ();
}

7. 自己抛出的异常必须要填写详细的描述信息。？？？？？？？？？？？？？
说明：便于问题定位。
示例：
throw new  IOException("Writing data error! Data: " + data.toString());

8. 运行期异常使用RuntimeException的子类来表示，不用在可能抛出异常的方法声明上加throws子句。非运行期异常是从Exception继承而来的，必须在方法声明上加throws子句。
说明：
非运行期异常是由外界运行环境决定异常抛出条件的异常，例如文件操作，可能受权限、磁盘空间大小的影响而失败，这种异常是程序本身无法避免的，需要调用者明确考虑该异常出现时该如何处理方法，因此非运行期异常必须有throws子句标出，不标出或者调用者不捕获该类型异常都会导致编译失败，从而防止程序员本身疏忽。
运行期异常是程序在运行过程中本身考虑不周导致的异常，例如传入错误的参数等。抛出运行期异常的目的是防止异常扩散，导致定位困难。因此在做异常体系设计时要根据错误的性质合理选择自定义异常的继承关系。
还有一种异常是Error 继承而来的，这种异常由虚拟机自己维护，表示发生了致命错误，程序无法继续运行例如内存不足。我们自己的程序不应该捕获这种异常，并且也不应该创建该种类型的异常。

9. 在程序中使用异常处理还是使用错误返回码处理，根据是否有利于程序结构来确定，并且异常和错误码不应该混合使用，推荐使用异常。
说明：
一个系统或者模块应该统一规划异常类型和返回码的含义。
但是不能用异常来做一般流程处理的方式，不要过多地使用异常，异常的处理效率比条件分支低，而且异常的跳转流程难以预测。

10. *注意运算符的优先级，并用括号明确表达式的操作顺序，避免使用默认优先级。
说明：防止阅读程序时产生误解，防止因默认的优先级与设计思想不符而导致程序出错。
示例：
下列语句中的表达式
word = (high << | low     (1)
if ((a | b) && (a & c))      (2)
if ((a | b) < (c & d))       (3)
如果书写为
high << 8 | low
a | b && a & c
a | b < c & d
（1）（2）虽然不会出错，但语句不易理解；（3）造成了判断条件出错。

11. *避免使用不易理解的数字，用有意义的标识来替代。涉及物理状态或者含有物理意义的常量，不应直接使用数字，必须用有意义的静态变量来代替。
示例：如下的程序可读性差。
if (state == 0)
{
    state = 1;
    ...  // program code
}

应改为如下形式：
private final static int TRUNK_IDLE = 0;
private final static int TRUNK_BUSY = 1;
private final static int TRUNK_UNKNOWN = -1;

if (state == TRUNK_IDLE)
{
    state = TRUNK_BUSY;
    ...  // program code
}

12. 数组声明的时候使用 int[] index ，而不要使用 int index[] 。
说明：使用int index[] 格式使程序的可读性较差
示例：
如下程序可读性差：
public int getIndex()[]
{
    ....
}
如下程序可读性好：
public int[] getIndex()
{
    ....
}

13. 调试代码的时候，不要使用 System.out 和 System.err 进行打印，应该使用一个包含统一开关的测试类进行统一打印。
说明：代码发布的时候可以统一关闭调试代码，定位问题的时候又可以打开开关。

14. 用调测开关来切换软件的DEBUG版和正式版，而不要同时存在正式版本和DEBUG版本的不同源文件，以减少维护的难度。

B. 建议
1. 记录异常不要保存exception.getMessage()，而要记录exception.toString()。
示例：NullPointException抛出时常常描述为空，这样往往看不出是出了什么错。

2. 一个方法不应抛出太多类型的异常。
说明： 如果程序中需要分类处理，则将异常根据分类组织成继承关系。如果确实有很多异常类型首先考虑用异常描述来区别，throws/exception子句标明的异常最好不要超过三个。

3. 异常捕获尽量不要直接 catch (Exception ex)，应该把异常细分处理。

4. *如果多段代码重复做同一件事情，那么在方法的划分上可能存在问题。 
说明：若此段代码各语句之间有实质性关联并且是完成同一件功能的，那么可考虑把此段代码构造成一个新的方法。

5. 对于创建的主要的类，最好置入main()函数，包含用于测试那个类的代码  。
说明：主要类包括：
1、能完成独立功能的类，如通讯。
2、具有完整界面的类，如一个对话框、一个窗口、一个帧等。
3、JavaBean 类。
示例：
public static void main(String[] arguments)
{
       CreateCircuitDialog circuitDialog1 = new CreateCircuitDialog (null, "Ciruit",  false);
       circuitDialog1.setVisible(true);
}

6. 集合中的数据如果不使用了应该及时释放，尤其是可重复使用的集合。？？？？？？？
说明：由于集合保存了对象的句柄，虚拟机的垃圾收集器就不会回收。

7. *源程序中关系较为紧密的代码应尽可能相邻。
说明：便于程序阅读和查找。
示例：矩形的长与宽关系较密切，放在一起。
rect.length = 10;
rect.width = 5;

8. *不要使用难懂的技巧性很高的语句，除非很有必要时。
说明：高技巧语句不等于高效率的程序，实际上程序的效率关键在于算法。