编程风格守则 一、本文目的 随着越来越多的项目启动，为了便于各位项目经理、程序员之前交流项目源程序，并且保证源程序的可读性，特制定本《编程风格守则》，本文的读者为项目经理、程序员，以期在编码过程之中，保持一致的风格，有利于软件工程项目的推行。本文在编写上力求求大同、存小异，在编程风格上分为两类，一类为强制风格，意为一定需要遵守，一类为推荐风格，意为希望程序员在编码时按照这样的风格。 二、概述 在软件工程领域，源程序的风格统一标志着可维护性、可读性，是软件项目的一个重要组成部分。而目前还没有成文的编码风格文档，以致于很多时候，程序员没有一个共同的标准可以遵守，编码风格各异，程序可维护性差、可读性也很差。 每位程序员都有自己的编程风格，因为每位程序员都有自己的学习过程，就象每个人的个性一样，所以编程风格是风彩各异、百花齐放；而从软件工程理论、实践来看，现代软件是多人合作的结晶，编程风格是否统一，直接关系到软件项目的可读性、可维护性、培训，继而对软件开发成本有着直接的关系，编程风格一致，软件项目易培训，其它人员接手老项目的时间缩短，便于程序员之间的交流。编程风格混乱，则其它人员接手老项目时间增长，同时随着项目的不断开发，项目或者单个源程序文件内有着多种编程风格，这样不利于整个项目的开展以及程序员之间的交流。 在开发中贯彻一定的程序开发准则，会使程序易维护、少错误，同时能够增强程序的团队开发性，使程序的专业化程度大大提高。为了保证系统开发效率，提高软件质量，以及在系统开发过程中便于团队成员间的沟通和交流，和有利于后期软件维护与升级，本文在参考业界已有的编码风格的基础上，描述了一个公司特有的风格，力求一种统一的编程风格，并从项目风格、代码文件风格、函数编写风格、变量风格、注释风格几个方面进行阐述。 三、项目风格 项目风格指的是针对整个项目，包括项目目录设置、相关库文件设置、集成开发环境设置等等的习惯约定。具体有如下风格守则： 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))// 正确 - 的确需要括号