Java编程规范

标签: java 编程 | 发表时间:2015-06-18 09: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编程风格指南

- - 行业应用 - ITeye博客
受不了的可以直接到以下网址查看. 作者:Hawstein 出处:http://hawstein.com/posts/google-java-style.html 声明:本文采用以下协议进行授权: 自由转载-非商用-非衍生-保持署名|Creative Commons BY-NC-ND 3.0 ,转载请注明作者及出处.

面向GC的Java编程

- - 并发编程网 - ifeve.com
Java程序员在编码过程中通常不需要考虑内存问题,JVM经过高度优化的GC机制大部分情况下都能够很好地处理堆(Heap)的清理问题. 以至于许多Java程序员认为,我只需要关心何时创建对象,而回收对象,就交给GC来做吧. 甚至有人说,如果在编程过程中频繁考虑内存问题,是一种退化,这些事情应该交给编译器,交给虚拟机来解决.

Java并发编程基础

- - 并发编程网 - ifeve.com
并发是一种能并行运行多个程序或并行运行一个程序中多个部分的能力. 如果程序中一个耗时的任务能以异步或并行的方式运行,那么整个程序的吞吐量和可交互性将大大改善. 现代的PC都有多个CPU或一个CPU中有多个核. 是否能合理运用多核的能力将成为一个大规模应用程序的关键. 进程是以独立于其他进程的方式运行的,进程间是互相隔离的.

java 并发编程 synchronized

- - Java - 编程语言 - ITeye博客
同步原语--synchronized. synchronized(class)很特别,它会让另一个线程在任何需要获取class做为monitor的地方等待.class与this做为不同的监视器可以同时使用,不存在一个线程获取了class,另一个线程就不能获取该class的一切实例.. ->线程各自获取monitor,不会有等待..

Java NIO编程的技巧和陷阱

- 小丑鱼 - 淘宝JAVA中间件团队博客
去年做的分享,一直上传slideshare失败,今天又试了下,成功了. 这个主题主要介绍Java NIO编程的技巧和陷阱,解读了一些NIO框架的源码,以及编写高性能NIO网络框架所需要注意的技巧和缺陷. 去年写了篇blog提供了pdf版本的下载,看这里.

JAVA接口编程的优点

- - ITeye博客
小弟刚工作两年文中所说都是通过自己工作中或做练习总结的经验,当然肯定不是那么准确,有不对之处望和谐指出,因为这个感觉完全是理论所以没有贴一段代码,有兴趣的就看看吧. 项目开发中绝对会碰到接口,但是为什么要使用接口成了绝大多数java程序员的疑问,为什么一定要写个没有实现任何功能的只有几个方名的类,可能也有一些人明白接口就是好,但好在哪里很难解释出来,我当初也是这样想的,但是当我一瞬间觉悟后发现这种想法很幼稚.

Java并发编程【1.2时代】

- - 并发编程网 - ifeve.com
         本文介绍了Java原生的多线程技术(1.2),通过详细介绍wait和notify相关的机制、基础的多线程技术以及基于这些技术的等待超时、线程间的通信技术和线程池高阶技术,最后通过一个基于线程池的简单文本web服务器—MollyServer,来阐明多线程带来好处. 通过介绍这些技术,展示了在没有使用Java并发包的时代(1.5-)是如何完成Java的多线程编程,为理解Java5提供了良好帮助.

Java 异步编程最佳实践

- - 鸟窝
最近异步编程非常流行, 主要是它能够在多核系统上提高吞吐率. 异步编程是一种编程方式,可以提高对UI的快速响应. Java中的异步编程模型提供了一致性的编程模型, 可以用来在程序中支持异步. 本文讨论了在使用Java执行异步操作应该遵循的最佳实践. 原文: Best Practices of Asynchronous Programming With Java.

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

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