编程规则（一）

编程风格守则
                                                 
一、本文目的
随着越来越多的项目启动，为了便于各位项目经理、程序员之前交流项目源程序，并且保证源程序的可读性，特制定本《编程风格守则》，本文的读者为项目经理、程序员，以期在编码过程之中，保持一致的风格，有利于软件工程项目的推行。本文在编写上力求求大同、存小异，在编程风格上分为两类，一类为强制风格，意为一定需要遵守，一类为推荐风格，意为希望程序员在编码时按照这样的风格。
二、概述
在软件工程领域，源程序的风格统一标志着可维护性、可读性，是软件项目的一个重要组成部分。而目前还没有成文的编码风格文档，以致于很多时候，程序员没有一个共同的标准可以遵守，编码风格各异，程序可维护性差、可读性也很差。
每位程序员都有自己的编程风格，因为每位程序员都有自己的学习过程，就象每个人的个性一样，所以编程风格是风彩各异、百花齐放；而从软件工程理论、实践来看，现代软件是多人合作的结晶，编程风格是否统一，直接关系到软件项目的可读性、可维护性、培训，继而对软件开发成本有着直接的关系，编程风格一致，软件项目易培训，其它人员接手老项目的时间缩短，便于程序员之间的交流。编程风格混乱，则其它人员接手老项目时间增长，同时随着项目的不断开发，项目或者单个源程序文件内有着多种编程风格，这样不利于整个项目的开展以及程序员之间的交流。
在开发中贯彻一定的程序开发准则，会使程序易维护、少错误，同时能够增强程序的团队开发性，使程序的专业化程度大大提高。为了保证系统开发效率，提高软件质量，以及在系统开发过程中便于团队成员间的沟通和交流，和有利于后期软件维护与升级，本文在参考业界已有的编码风格的基础上，描述了一个公司特有的风格，力求一种统一的编程风格，并从项目风格、代码文件风格、函数编写风格、变量风格、注释风格几个方面进行阐述。
三、项目风格
项目风格指的是针对整个项目，包括项目目录设置、相关库文件设置、集成开发环境设置等等的习惯约定。具体有如下风格守则：
3.1    项目取名
项目名称在项目启动前由项目规划人员取。
3.2    项目目录设置
为保证项目的备份方便、快捷，可将所有该项目有关的文件全部放到统一的目录之下，项目目录名称一律用英文，项目总目录名称使用项目名称(如AuSoft)，在此目录下，建立一个source目录，必须有一个doc目录，一个“相关技术”目录，建立一个，一个，然后按模块分别建立不同的存放目录，，
一级目录    二级目录    三级目录    备注
项目名称
如AuSoft40    AuSoftbeans    public    项目公共部分的目录
        base    基础库目录
        功能模块……    按模块需要建立不同的存放目录
    AuSoftdoc    存放项目相关的公司自己创作的各种开发文档
    AuSoftresource    项目组成员自己根据所存放的主题取名    存放项目组成员根据项目开发需要而收集的相关的各种技术文档，源码等
    AuSoftpages    public    项目公共部分的目录
        base    基础库目录
        功能模块……    按模块需要建立不同的存放目录
3.3    集成开发环境内设置
公司规定所有开发人员必须使用Eclipse或者Jcreator开发工具，每个项目在开发环境的设置都采用相对路径的设置，不可采用绝对路径，保证其备份到光盘设备后，恢复到硬盘后，不需要再过多的设置就可直接编译。
3.4    项目修改记录追踪
项目修改记录跟踪借助于版本控制软件工具CVS，用以记载项目产生以来所有的改动，其格式必须如下：
日期：         2004/08/08
修改人：    XXX
修改主题：     底层通讯由于MODEM响应代码而引起的不稳定现象
相关修改文件： CommLayer.jsp
修改内容详细描述：
 四、文件风格
4.1    文件命名
文件命名要能大体上表达出此文件主要包含哪些内容，是做什么用的等主体功能，采用文件所体现的主体功能的汉语拼音(全拼与简拼根据文件长度自行决定)来命名，文件命名不能少于6个字母，也不能大于20个字母。
4.2    文件头部注释
文件头部注释主要是表明该文件的一些信息，并且要符合JAVADOC的格式，其格式如下：
/*
 *  文件名：
 *  创建时间：
 *  创建者：
 *  内容描述：
 * 
 */
4.3    空行约定
文件之中不得存在无规则的空行，比如说连续十个空行，一般来讲函数与函数之前的空行为3行，在函数体内部，在逻辑上独立的两个函数块可适当空行，一般为1-2行。
4.4    页宽
页宽应该设置为80字符. 源代码一般不会导致无法完整显示, 超长的语句应该在一个逗号或者一个操作符后折行. 一条语句折行后, 应该比原来的语句再缩进3个字符. 
4.5    文件规格化功能键
源文件在编写完毕时，有一种排版格式化插件？，进行文件规格化，如果不能进行格式化，按下面的代码排版格式手工进行格式化。
五、代码与注释风格
命名规则
所有方法、变量、包、类等的命名要能大体上表达出它主要包含哪些内容，是做什么用的等主体功能，采用它所体现的主体功能的汉语拼音(全拼与简拼根据文件长度自行决定)来命名，文件命名不能少于6个字母，也不能大于20个字母。
1 package的命名
package 的名字应该都是由一个小写字母组成。 
例如：package quanxianpackage;

2 class 的命名 
class 的名字必须由大写字母开头而其他字母都小写的单词组成,下一个字母的开头大写，其余的字母小写。 
例如：class OracleConnectionBean

3 class 变量的命名 
变量的名字必须用一个小写字母开头。后面的单词用大写字母开头。 
例如：OracleOCIConnection oracleConn=null;

4 static final 变量的命名 
static final 变量的名字应该都大写，并且指出完整含义。 
例如：static final CONTEXT_TYPE=”GB2312”;//设置页面字符

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

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

7 方法的参数 
使用有意义的参数命名，如果可能的话，使用和要赋值的字段一样的名字： 
setUserName(String userName){
    this.userName=userName;
}
注释风格
所有注释必须符合JAVADOC注释规范
不需要进入JAVADOC的  单行注释用双斜杠进行注释；多行注释用/* */进行注释；
package 行要在 import 行之前，如果 import 行中包含了同一个包中的不同子目录，则应该用 * 来处理。 例如：

package com.test;
import java.io.*;
这里 java.io.* 使用来代替InputStream and OutputStream 的。 

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

/**
 * 在这里添加类的描述。
 *
 * 时间  
 * 作者  Zhichao Zhao
 */

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

public class Test 
extends SomeClass
implement SomeClass{
/** 在这里添加类的执行注释。 */

接下来是类的成员变量： 

/**classVar1 成员变量的注释 */
    public static int classVar1;

    /**
     * classVar2 成员变量的注释第一行
     * 成员变量的注释第二行
     */
    private static Object classVar2;

    /**
     * ...Test 构造方法注释...
     */
    public Test() {
    }

    /**
     * ...doSomething 方法的简述...
     */
public void doSomething() 
{
    }

    /**
     * ...doSomethingElse 方法的简述...
*@参数 someParam true 表示有权限 fasle 表示没有权限
*@返回值 没有返回值
*
     */
public void doSomethingElse(boolean someParam) 
{
}

/**
     * @参数 UserName 用户输入的用户名称
     * @返回值 返回用户输入的用户名称
     * @关键逻辑说明 返回用户输入的用户名称
* @exception NullPointerException 当UserName的值为null时，
* 返回一个空指针异常。
     */
    
public String doSomething(String UserName){
try{
this.classVar1=UserName.trim();
}
catch(NullPointerException e){
}
return classVar1;
}
}

所有成员变量必须生成文档（JavaDoc）。 

代码缩进
每一个嵌套的函数块，使用一个TAB缩进（可以设定为3个空格），大括号必须放在条件语句的下一行(也可以在一行)，单独成一行，便于匹对：
if(condition){
    while(condition){
    }
}

括号
大括号{}的要求
if(condition){
    while(condition){
    }
}

小括号()的要求
左括号和后一个字符之间不应该出现空格, 同样, 右括号和前一个字符之间也不应该出现空格. 下面的例子说明括号和空格的错误及正确使用: 

CallProc( AParameter ); // 错误 
CallProc(AParameter); // 正确 

不要在语句中使用无意义的括号. 括号只应该为达到某种目的而出现在源代码中。下面的例子说明错误和正确的用法: 

if ((I) = 42) {a=5;} // 错误 - 括号毫无意义 
if((I==4)and (I<5))// 正确 - 的确需要括号