Java编程规范

转： http://blog.csdn.net/evankaka/article/details/46538109

 

一.    编写背景

本文档的编写从简，绝大多数内容以条款或者表格形式列出，不做过多的补充说明,代码格式规范遵循eclipse的默认编码规范要求.

二.    适用范围

后台开发人员

总则

规范制定总则

•    简单，易执行

命名总体原则

1.    名字含义要明确，做到见名知义,如: User,Role, UserManager
2.    尽量使用英文名字作为变量名，如果要使用中文，请写上备注.
如：var hbType = null;// hb是中文“货币”的首字母缩写.
3.    采用大小写混合形式命名，提高名字的可读性
正确：UserManager
错误: usermanager
4.    尽量少用缩写，但如果一定要使用，就要谨慎地使用。
应该保留一个标准缩写的列表，并且在使用时保持一致。例如，想对单词“number”采用缩写，使用 num 这种格式，并且只使用这一种形式.注意：要维护缩写词汇列表.
5.    所有文件的名称都是大写字母开头，大小写混合, 如UserList.jsp
6.    所有目录的名称都是小写字母开头，大小写混合, 如userType
7.    变量名不能以下划线开头，如“_account”,”_userName”是不允许的，因为下划线开头的变量可能被OWK平台做为保留字占用.
8.    避免使用相似或者仅在大小写上有区别的名字
例如，不应同时使用变量名 persistentObject 和 persistentObjects，以及 anSqlDatabase 和 anSQLDatabase。

代码注释原则

1.    注释应该简单清晰，避免使用装饰性内容，也就是说，不要使用象广告横幅那样的注释语句。
2.    代码注释的目的是要使代码更易于被同时参与程序设计的开发人员以及其他后继开发人员理解。 
3.    先写注释，后写代码。
写代码注释的最好方法是在写代码之前就写注释。这使你在写代码之前可以想想代码的功能和运行。而且这样确保不会遗漏注释。(如果程序的逻辑稍微复杂点的话，这样做非常有效)
4.    注释信息不仅要包括代码的功能，还应给出原因。
例如，下面例 1 中的代码显示金额在 $1,000 以上（包括 $1,000）的定单可给予 5% 的折扣。为什么要这样做呢？难道有一个商业法则规定大额定单可以得到折扣吗？这种给大额定单的特殊是有时限的呢，还是一直都这样？最初的程序设计者是否只是由于慷慨大度才这样做呢？除非它们在某个地方（或者是在源代码本身，或者是在一个外部文档里）被注释出来，否则你不可能知道这些。 
if (grandTotal >= 1000.00)
{
grandTotal = grandTotal * 0.95;
}

三    规范内容

命名

包

包结构定义=${包单元}[.${包单元}]*

说明：

     1:一个包是由一个或多个构造单元组成,各构造单元之间以点号”.”隔开

      2:一个包单元由一个或多个词组成
      3:包单元应该是名词
•    业务系统的包结构是com.cmb.zct.${业务系统名字}.${模块名}
•    包名全部小写，如：com.cmb.zct.tx.OA.common是不允许的.但有种情况下允许出现大写字母,就是当包单元是由多个词组成时.如： com.cmb.zct.tx.oa.userType.

类

•    使用完全的英文描述符，所有单词的第一个字母要大写，并且单词中大小写混合。
•    类名是名词或名词词组.如 LogManager
•    工具类以Util结尾 . 如FileUtil,StrUtil
•    异常类以Exception结尾.如RootDirNotExistsException
•    抽象类名以Abstract开头 AbstractGenerator
•    工厂类以Factory结尾,如 ConnFactory
•    接口同类名，大小写混合..

方法

•    成员函数的命名应采用完整的英文描述符，大小写混合使用：所有中间单词的第一个字母大写。成员函数名称的第一个单词常常采用一个有强烈动作色彩的动词。首个单词小写。如：getUserInfo, removeEquipment   

参数变量

  以 小写p开头 
       如
       public void sendMessage(String pMessage){
         ...............
       }
注意：javabean 的参数变量不带p。

常量名

采用完整的英文大写单词，在词与词之间用下划线连接。
MAX_VALUE，DEFAULT_START_DATE

目录名

     同包名，小写字母开头，如果有多个单词构成，则第2个以后的单词以大写字母开头。如user, userType目录

文件名

  同类名命名规则，大写字母开头，大小写混合。如：EquipmentList.jsp
  模块相关文件命名约束，为了方便说明，${MODEL_NAME}代表实际模块的名称,那各文件的名字必须满足下表格式要求.
文件                                   格式                                     举例
业务组件接口    I${MODEL_NAME}Facade.java    IUserFacade.java
服务组件接口    I${MODEL_NAME}Service.java    IUserService.java
业务组件实现类    ${MODEL_NAME}FacadeImpl.java    UserFacadeImpl.java
服务组件实现类    ${MODEL_NAME}ServiceImpl.java    IUserServiceImpl.java
测试类    ${MODEL_NAME}ServiceTest.java    UserServiceTest.java
        
        

模块

配置文件    Spring配置文件    ${MODEL_NAME}.spring.xml    User.spring.xml
     Sqlmap配置    ${MODEL_NAME}.sqlmap.xml    User.sqlmap.xml
    种子文件    ${MODEL_NAME}Service.seed.xml    UserService.seed.xml
            
            

JAVA源文件结构

/*
*Copyright (c) 2007-2008 
*/

package com.owk.sgtz.util;

import java.io.Serializable;
import java.util.List;

/**
 * 
 * @author HO074337
 *
 */
public class Test extends Object implements Serializable{
    
    /* 变量注释 */
    public static final int PKG_HEADER_MAX_LEN = 20;
    /* */
    protected static int i = 0;
    int j = 0;
    private int k;


    
    /**
     *方法注释
     * @param i
     */
    public Test(int i){
        
    }
    
    /***
     * 方法注释
     *
     */
    public void printInfo(){
        
    }
    
}

说明：
•    首行是版权信息
•    空一行，定义包名
•    空一行，声明要import的类
•    空一行，编写类的注释
•    紧挨着，定义类
•    空一行，定义变量
•    空一行，定义构造函数
•    空一行，定义方法

注释

概念

Java程序有两类注释：

    实现注释(implementation comments)和文档注释(document comments)。实现注释是那些在C++中见过的，使用/*...*/和//界定的注释。

    文档注释(被称为"doc comments")是Java独有的，并由/**...*/界定。文档注释可以通过javadoc工具转换成HTML文件.本规范只对文档注释进行约束，程序注释由开发人员自行把握,但应该遵循代码注释原则

类的注释

/**
 * 
 * @author HO074337
 * @version 1.0
* 创建日期：20071010 
 *
* 功能描述：
 *   类的功能描述，阐述这个类的主要功能
 *   
 * 已知的问题:
 *   如果一个类有任何突出的问题，应说明出来，让其他的开发者了解这个类的缺点/难点。
 *   此外，还应注明为什么不解决问题的原因
 *   
 * 维护历史:
 *   列出日期、类的作者和修改概要。这样做的目的是让进行维护的程序员了解过去曾对一个
 *   类所做的修改，是谁做了什么样的修改
 *   如：
 *   huangyh 20071010 
 *    增加了getUserById(String)方法,使用该方法可以获取用户对象
 *    
 *   zhangw  20071008
 *    将private方法 removeUser() 设置为public,因为在 XX模块需要使用.
 *    
 */

变量注释

    /**
     * 通讯报头的最大长度
     */
    public static final int PKG_HEADER_MAX_LEN = 20;
注意：所有public ,protected或默认的变量，都必须采用文档注释符号，因为这些注释信息需要
导出到文档。
Private变量，可以用单行注释，多行注释，或者文档注释，不做限制

变量描述要说明变量的用途.如果是枚举性质的变量，请注释清楚有效值范围.

方法注释

    /**
     * 功能描述：
     *   方法提供什么功能.
     *   
     * 已知问题:
     *   如果方法的实现存在某些问题时，需要在这进行说明，以便后续维护人员
     *   把问题解决，或者规避.
     * 
     * 使用示例:
     *   简单的函数调用示例
     *   
     * @param pMsg 参数名称 参数描述
     * @return    返回值说明
     * @exception 异常说明
     */

任务标注

在注释中使用TODO来标识某些未实现(bogus)的但可以工作(works)的内容。用FIXME来标识某些假的和错误的内容。 
   如:      /**
         * TODO: XXX有效性检验.
         */
   /**
* FIXME: 这段代码存在严重的性能问题，系统正式发布前一定要修复
*/
这些标住信息在eclipse的Tasks视图中可以看
 
异常
1.    所有业务异常（帐号不存在，密码错误等）都必须直接或者间接从com.cmb.zct.common.exception. BusinessException派生
2.    所有系统异常（主键冲突，SQL语句本身句法错误）都必须直接或者间接从com.cmb.zct.common.exception.SysException 派生

日志

1.    不准使用System.out.println/System.err.println 输出调试信息
2.    统一使用common log 输出日志
3.    日志对象的定义
private final Log log = LogFactory.getLog( BaseJDBCDAO.class );
或者
private final static Log log = LogFactory.getLog( BaseJDBCDAO.class );

编码方式

所以牵涉到编码方式的地方，全部统一使用utf-8编码
编程惯例
1.    类成员变量不设置为public 的，除非是static final 常量
2.    该用类名访问静态方法而不是对象. 如: StringUtil.trim
3.    将工具类的构造函数设置为private,避免client端构造对象来调用工具方法
4.    位于for循环中作为计数器值的数字常量，除了-1,0和1之外，不应被直接写入代码.应该先定义常量变量
5.    一般而言，在含有多种运算符的表达式中使用圆括号来避免运算符优先级问题，是个好方法。即使运算符的优先级对你而言可能很清楚，但对其他人未必如此。你不能假设别的程序员和你一样清楚运算符的优先级。 
if (a == b && c == d) // AVOID! 
if ((a == b) && (c == d)) // RIGHT 
6.    对于返回List/Set/Map的方法，当集合中不存在记录时，返回空的List/Set/Map,而不是null. 在java.util.Collections类中存在3个对应的空对象 EMPTY_LIST, EMPTY_SET和EMPTY_Map
7.    session,application变量的key值，不能只是个简单的名字，为了避免冲突,通常需要给key值带上包名。
如： 
  USER_DATA_KEY是用来保存登陆用户信息的
private static final String PACKAGE_NAME = Constants.class.getName();    
    public static final String USER_DATA_KEY = PACKAGE_NAME + ".userData";
排版/其它
1.    代码风格统一采用Eclipse默认的风格，请选定代码后使用快捷键“CTRL+SHIFT+F”格式化代码；
2.    每行只包含一条语句.不允许在一行中出现这种情况:argv++; argc--; 
3.    所有if,for,while,do while等中的语句块都应该包含在{}里. 这样便于添加语句而无需担心由于忘了加括号而引入bug
4.    单行长度尽量避免一行的长度超过80个字符
5.    推荐一行一个声明，因为这样以利于写注释
6.    避免声明的局部变量覆盖上一级声明的变量。例如，不要在内部代码块中声明相同的变量名
7.    方法内的局部变量和方法的第一条语句之间使用空行间隔
8.    块注释（参见"5.1.1"）或单行注释（参见"5.1.2"）之前插入空行间隔
9.    一个紧跟着括号的关键字应该被空格分开.如: while ( true ){}
10.    参数列表的逗号后面要加空格。如：getBranch(String branchCode, String subbranchCode);
11.    for语句中的表达式应该被空格分开 for(int I=0; I<10; I++)
12.    一元操作符和操作数之间不因该加空格，比如：负号("-")、自增("++")和自减("--")
13.    强制转型后应该跟一个空格myMethod((byte) aNum, (Object) x);