Java编程规范

标签: java 编程 规范 | 发表时间:2015-06-18 17:31 | 作者:z724130632
出处:http://www.iteye.com

转: 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);



已有 0 人发表留言,猛击->> 这里<<-参与讨论


ITeye推荐



相关 [java 编程 规范] 推荐:

Java编程规范

- - Web前端 - ITeye博客
本文档的编写从简,绝大多数内容以条款或者表格形式列出,不做过多的补充说明,代码格式规范遵循eclipse的默认编码规范要求. •    简单,易执行. 1.    名字含义要明确,做到见名知义,如: User,Role, UserManager. 2.    尽量使用英文名字作为变量名,如果要使用中文,请写上备注.

Java编程风格与命名规范整理

- - BlogJava-首页技术区
基本命名规范     包命名.     包名按照域名的范围从大到小逐步列出,恰好和Internet上的域名命名规则相反. ”连接的标识符构成,通常第一个标识符为符合网络域名的两个或者三个英文小写字母.     类的名字必须由大写字母开头而单词中的其他字母均为小写;如果类名称由多个单词组成,则每个单词的首字母均应为大写例如TestPage;如果类名称中包含单词缩写,则这个所写词的每个字母均应大写,如:XMLExample,还有一点命名技巧就是由于类是设计用来代表对象的,所以在命名类时应尽量选择名词.

java编码规范

- - ITeye博客
   总结前期做的几个项目,个人认为代码的规范对团队的协作有着密切的关系. 现将一些常用的约束总结如下,以便今后参阅:. 1、所有的类、属性、方法都遵守以字母和数字为主,尽量不要参与特殊符号如下划线. 其次,除类名开头字母大写外,其他名字都要小写,然后第二个后的单词首字母大写,长度在30个字符以内.

javascript 编程规范

- 红茶 - 博客园-Ruby&#39;s Louvre
为公司起草的javascript编程规范,参考了网上的许多资料,尤其是google的规范. 现在放出来,希望能抛砖引玉,大家多提宝贵意见. 本规范是针对javascript函数式编程风格与公司严重依赖于jQuery进行编码的现实制定出来. 禁止使用eval,with与caller(ecma262 v5 的use strict要求).

python编程规范

- - 互联网 - ITeye博客
@FileName: @Author:[email protected] @Create date: @description:用一行文字概述模块或脚本,用句号结尾. 不影响编码的效率,不与大众习惯冲突.. 使代码的逻辑更清晰,更易于理解..   *所有的 Python 脚本文件都应在文件头标上如下标识或其兼容格式的标识.

Java/Android编码规范

- - CSDN博客推荐文章
1.        为什么需要编码规范?. 编码规范对于程序员而言尤为重要,有以下几个原因:. l        一个软件的生命周期中,80%的花费在于维护. l        几乎没有任何一个软件,在其整个生命周期中,均由最初的开发人员来维护. l        编码规范可以改善软件的可读性,可以让程序员尽快而彻底地理解新的代码.

java代码开发规范

- - BlogJava_首页
格式规范:                                                                      .       1、TAB空格的数量. 编辑器上的TAB空格数量统一取值为4.       2、换行, 每行120字符.       3、if语句的嵌套层数3层以内   .

[链接帖] 新的Java语言规范、Java虚拟机规范

- Wong - Script Ahead, Code Behind
随着7月28日,也就是Java SE 7预定的发布日期越来越近,相关的一些规范也已得到或即将得到批准. 这里主要关注的是下面几个规范:. Java语言规范,JSR 901的第三修订版(Maintenance Review 3)已经完成审核但尚未正式得到批准. Java虚拟机规范,JSR 924的第三修订版(Maintenance Review 3)在今年3月19日已经得到批准.

android 编程代码规范

- - CSDN博客推荐文章
                学习android开发已经有很长时间了,但是有时代码却很少用规范的模式进行书写,下面就简要的总结了自己学习的代码规范. 一、关于一些常量值资源的书写规范. 颜色值有RGB和透明信息Alpha组成,以#开头, 形式有 #RGB                        #ARGB                        #RRGGBB                    #AARRGGBB.

dotnet core 编程规范

- - 林德熙
本文实际只是翻译 .NET Core foundational libraries 官方文档的编码风格. 在 .NET Core foundational libraries项目使用的编程规范默认就是 VisualStudio 默认样式. 花括号使用 Allman style 风格,所有的花括号在新的一行开始.