编程规则(一)

编程风格守则

                                                 

一、本文目的

随着越来越多的项目启动,为了便于各位项目经理、程序员之前交流项目源程序,并且保证源程序的可读性,特制定本《编程风格守则》,本文的读者为项目经理、程序员,以期在编码过程之中,保持一致的风格,有利于软件工程项目的推行。本文在编写上力求求大同、存小异,在编程风格上分为两类,一类为强制风格,意为一定需要遵守,一类为推荐风格,意为希望程序员在编码时按照这样的风格。

二、概述

在软件工程领域,源程序的风格统一标志着可维护性、可读性,是软件项目的一个重要组成部分。而目前还没有成文的编码风格文档,以致于很多时候,程序员没有一个共同的标准可以遵守,编码风格各异,程序可维护性差、可读性也很差。

每位程序员都有自己的编程风格,因为每位程序员都有自己的学习过程,就象每个人的个性一样,所以编程风格是风彩各异、百花齐放;而从软件工程理论、实践来看,现代软件是多人合作的结晶,编程风格是否统一,直接关系到软件项目的可读性、可维护性、培训,继而对软件开发成本有着直接的关系,编程风格一致,软件项目易培训,其它人员接手老项目的时间缩短,便于程序员之间的交流。编程风格混乱,则其它人员接手老项目时间增长,同时随着项目的不断开发,项目或者单个源程序文件内有着多种编程风格,这样不利于整个项目的开展以及程序员之间的交流。

在开发中贯彻一定的程序开发准则,会使程序易维护、少错误,同时能够增强程序的团队开发性,使程序的专业化程度大大提高。为了保证系统开发效率,提高软件质量,以及在系统开发过程中便于团队成员间的沟通和交流,和有利于后期软件维护与升级,本文在参考业界已有的编码风格的基础上,描述了一个公司特有的风格,力求一种统一的编程风格,并从项目风格、代码文件风格、函数编写风格、变量风格、注释风格几个方面进行阐述。

三、项目风格

项目风格指的是针对整个项目,包括项目目录设置、相关库文件设置、集成开发环境设置等等的习惯约定。具体有如下风格守则:

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))// 正确 - 的确需要括号  

 

你可能感兴趣的:(编程)