1、软 件 编 程 规 范 -Java（正式版）中兴软件技术（南昌）有限公司版权所有 不得复制软件编程规范Java 篇第 2 页 共 36 页修订记录日 期 修订版本 描 述 修改人2006-03-08 正式版 完成 编程规范小组软件编程规范Java 篇第 3 页 共 36 页目 录目 录 3前 言 41 基本原则 52 文件结构 62.1 基本格式 .62.2 对齐 .82.3 空行空格 .92.4 断行 .113 注释 144 命名规则 205 声明 266 表达式与语句 277 类和接口 31附 录 34附录 A 编程模版 34参考文献 36软件编程规范Java 篇第 4 页 共 36 页前
2、 言软件编程规范的目的是为了统一公司软件编程风格，提高软件源程序的可读性、可靠性和可重用性，提高软件源程序的质量和可维护性，减少软件维护成本，最终提高软件产品生产力。本规范是针对 JAVA 语言的编程规则。本规范适用于公司所有产品的软件源程序，同时考虑到不同产品和项目的实际开发特性，本规范分成规则性和建议性两种：对于规则性规范，要求所有软件开发人员严格执行；对于建议性规范，各项目编程人员可以根据实际情况选择执行。本规范的示例都以 JAVA 语言描述。本规范的内容包括：基本原则、文件结构、注释、命名规则、声明、表达式与语句、类和接口等。规范最后给出了标准模板供软件人员参考。本规范由软件编程规范小
3、组编写本规范自生效日期起，对以后新编写的和修改的代码有约束力。对以前的代码不要求进行修改。对于由开发工具自动生成的代码可以不约束。对本规范中所使用的术语解释如下：原则：编程时应该坚持的指导思想。规则：编程时必须遵守的约定。建议：编程时必须加以考虑的约定。说明：对此规则或建议的必要的解释。正例：对此规则或建议给出的正确例子。反例：对此规则或建议给出的反面例子。软件编程规范小组2006年3月8日软件编程规范Java 篇第 5 页 共 36 页1 基本原则说明：这是软件开发的基本要点，软件的生命周期贯穿产品的开发、测试、生产、用户使用、版本升级和后期维护等长期过程，只有易读、易维护的软件代码才具有生
4、命力。说明：简单是最美。保持代码的简单化是软件工程化的基本要求。不要过分追求技巧，否则会降低程序的可读性。说明：编程时以公司的规范为准，公司的规范没有规定的内容参考上面的标准。说明：编程首先考虑的是满足正确性、健壮性、可维护性、可移植性等质量因素，其次考虑程序的效率和资源占用。说明：尽量选择可借用的代码，对其修改优化以达到自身要求。说明：事实上，我们无法做到完全消除错误，但通过不懈的努力，可以减少同样的错误出现的次数。【原则 1-1】首先是为人编写程序，其次才是计算机。【原则 1-2】保持代码的简明清晰，避免过分的编程技巧。【原则 1-3】所有的代码尽量遵循 SUN 的Code Convent
5、ions for the JavaTM Programming Language标准（参见： http:/ 。【原则 1-4】编程时首先达到正确性，其次考虑效率。【原则 1-5】保持一致性，尽可能多的使用相同的规则。【原则 1-6】尽可能复用、修正原有的代码。【原则 1-7】 尽量减少同样的错误出现的次数。软件编程规范Java 篇第 6 页 共 36 页2 文件结构程序布局的目的是显示出程序良好的逻辑结构，提高程序的准确性、连续性、可读性、可维护性。更重要的是，统一的程序布局和编程风格，有助于提高整个项目的开发质量，提高开发效率，降低开发成本。同时，对于普通程序员来说，养成良好的编程习惯有助于
6、提高自己的编程水平，提高编程效率。因此，统一的、良好的程序布局和编程风格不仅仅是个人主观美学上的或是形式上的问题，而且涉及到产品质量，涉及到个人编程能力的提高，必须引起大家重视。2.1 基本格式正例:package com.zte; import java.awt.peer.CanvasPeer;import java.io.*;import com.zte.ums.uep.*;/* 文件名称: 题目名称* 文件描述: 本类描述* 版权所有: 版权所有(C)2006* 公 司: 中兴软件技术（南昌）有限公司 * 内容摘要: / 简要描述本文件的内容，包括主要模块、函数及其功能的说明* 其他说明
7、: / 其它内容的说明* 完成日期：/ 输入完成日期，例：2006 年 2 月 25 日* 修改记录 1: / 修改历史记录，包括修改日期、修改者及修改内容* * 修改日期：* 版 本 号：* 修 改 人：* 修改内容：* * 修改记录 2：* version 1.0* author 作者姓名【规则 2-1-1】源代码文件（.java）的布局顺序是：包、import 语句、注释、类。软件编程规范Java 篇第 7 页 共 36 页*/public class ClassName说明：package 语句其后可跟 import 语句，而且与 package 间隔一个空行。import 包的排列顺
8、序为 java 开头的包在最前面，接下来是引自外部的包，再接下来是应用程序自身的包，即 import 中标准的包名要在本地的包名之前，而且按照字母顺序排列。正例:package com.zte; import java.awt.peer.CanvasPeer; /java 自身的包import java.io.*;import com.klg.field.*; /第三方的包import com.zte.ums.uep.*; /程序自身的包说明：包括空格在内不超过 120 列。说明：这样可以防止书写失误，也易于阅读。正例：if (varible1 文件名称: 题目名称* 文件描述: 本类描述*
9、版权所有: 版权所有(C)2006* 公 司: 中兴软件技术（南昌）有限公司 * 内容摘要: / 简要描述本文件的内容，包括主要模块、函数及能的说明* 其他说明: / 其它内容的说明* 完成日期：/ 输入完成日期，例：2006年2月25日* 修改记录1: / 修改历史记录，包括修改日期、修改者及修改内容* * 修改日期：* 版 本 号：* 修 改 人：* 修改内容：* * 修改记录2：* version 1.0* author 作者姓名*/说明：注释必须列出：功能描述、输入参数、返回值等，对于成员属性的 get/set 操作可以不加注释。正例：下面是公共方法头部的注释：/* 这是对下面的方法进
10、行文档型注释的第一行内容。* 这是对下面的方法进行文档型注释的第二行内容。* param name 用户的名称* return 返回用户的名称*/public String getName(String name)return name;【规则 3-3】公共方法前面应进行文档型注释，列出：函数的目的/功能、输入参数、返回值等。软件编程规范Java 篇第 16 页 共 36 页说明：在使用缩写时或之前，应对缩写进行必要的说明。正例： 如下书写结构比较清晰/ 获得子系统索引 subSysIndex = data.getSysIndex;/ 代码段 1 注释 代码段 1 /* 代码段 2 注释 */
11、 代码段 2 反例 1：如下例子注释与描述的代码相隔太远。/* 获得子系统索引 */subSysIndex = subSys.getSysIndex();反例 2：如下例子注释不应放在所描述的代码下面。subSysIndex = subSys.getSysIndex();/* 获得子系统索引 */反例 3：如下例子，显得代码与注释过于紧凑。/* 代码段 1 注释 */ 代码段 1 /* 代码段 2 注释 */ 代码段 2 【规则 3-4】保证代码和注释的一致性。修改代码的同时修改相应的注释，不再有用的注释要删除。【规则 3-5】注释应与其描述的代码相近，对代码的注释应放在其上方（需与其上面的代
12、码用空行隔开）或右方（对单条语句的注释）相邻位置，不可放在下面。【规则 3-6】注释与所描述内容进行同样的缩进。软件编程规范Java 篇第 17 页 共 36 页说明：这样可使程序排版整齐，并方便注释的阅读与理解。正例： 如下注释结构比较清晰int doSomething()/* 代码段 1 注释 */ 代码段 1 /* 代码段 2 注释 */ 代码段 2 反例：如下例子，排版不整齐，阅读不方便；int doSomething()/* 代码段 1 注释 */ 代码段 1 /* 代码段 2 注释 */ 代码段 2 说明：有效的注释是指在代码的功能、意图层次上进行注释，提供有用、额外的信息。注释的
13、原则是有助于对程序的阅读理解，注释不宜太多也不能太少，注释语言必须准确、易懂、简洁。正例：对于public 型变量的单行声明：/* classVar1 对classVar1的声明 */public static int classVar1;对于public 型变量的多行声明：/* classVar1 对classVar1的声明第一行* 对classVar1的声明第二行（继续对classVar1 的声明）*/建议 3-1一般情况下，源程序有效注释量必须在 20以上。建议 3-2Java 语言中，公共的属性采用单行文档注释，对于需要比较多的声明的，可进行多行注释。软件编程规范Java 篇第 18
14、页 共 36 页public static int classVar1;对于public 型变量的多行声明：/* classVar1 对classVar1的声明第一行* 对classVar1的声明第二行（继续对classVar1 的声明）*/public static int classVar1;说明：此时注释可以用英文，方便查找对应的语句。正例： void doSomething() if () while () / end of while () / 指明该条 while 语句结束 / end of if () / 指明是哪条语句结束 / end of void main（） / 指明函数
15、的结束说明：这些语句往往是程序实现某一特殊功能的关键，对于维护人员来说，良好的注释有助于更好的理解程序，有时甚至优于看设计文档。说明：清晰准确的方法、变量的命名，可增加代码的可读性，减少不必要的注释。建议 3-3包含在 中代码块的结束处应加注释，便于阅读。特别是多分支、多重嵌套的条件语句或循环语句。建议 3-4对分支语句（条件分支、循环语句等）应编写注释。建议 3-5通过对方法、变量等正确的命名以及合理地组织代码结构，使代码成为自注释的。建议 3-6尽量避免在注释中使用缩写，特别是不常用缩写。软件编程规范Java 篇第 19 页 共 36 页说明：在使用缩写时，应对缩写进行必要的说明。软件编程
16、规范Java 篇第 20 页 共 36 页4 命名规则好的命名规则能极大地增加可读性和可维护性。同时，对于一个有上百个人共同完成的大项目来说，统一命名约定也是一项必不可少的内容。本章对程序中的所有标识符（包括包、变量名、常量名、方法名、类名等）的命名做出约定。对同一个项目内应使用统一的词汇表。说明：标识符应当直观且可以拼读，可望文知义，避免使人产生误解。程序中的英文单词一般不要太复杂，用词应当准确。说明：这样做的目的是为了使程序易读。因为 variable_name 和 variable_name 很难区分，下划线符号_若出现在标识符头或结尾，容易与不带下划线_的标识符混淆。说明：对于标识符应
17、当使用完整的英文进行描述，对于整个描述较长的，可对单词进行缩略。较短的单词可通过去掉“元音”形成缩写，较长的单词可取单词的头几个字母形成缩写，一些单词有大家公认的缩写，常用单词的缩写必须统一。协议中的单词的缩写与协议保持一致。对于某个系统使用的专用缩写应该在某处做统一说明。设计命名中应该慎用缩写命名。如要采用，则应采用统一的缩略规则，并且在代码的相应部分统一采用缩写。例如，采用 num 作为 number 的缩写，那么在整个代码中应该始终使用该缩写。正例：如下单词的缩写能够被大家认可：temp 可缩写为 tmp ；flag 可缩写为 flg ；statistic 可缩写为 stat ；incr
18、ement 可缩写为 inc ；message 可缩写为 msg ；【规则 4-1】标识符要采用英文单词或其组合，便于记忆和阅读，切忌使用汉语拼音来命名。【规则 4-2】标识符只能由 26 个英文字母，10 个数字及下划线的一个子集来组成，并严格禁止使用连续的下划线。用户定义的标识符下划线不能出现在标识符的头尾。【规则 4-3】标识符应当使用完整的英文描述，标识符的命名应当符合“min-length 说明：软件开发人员应注意软件用户的一些约定术语，不应当随意的创造术语，这会降低软件的易用性。说明：命名时应避免采用几乎相同的名称。例如，变量名称 persistentObject 和persist
19、entObjects 不应当同时运用；anSqlDatabase 和 anSQLDatabase 也不应同时使用。说明：下面是一些在软件中常用的反义词组。add / remove ； begin / end ； create / destroy ； insert / delete ；first / last ； get / set ； increment / decrement ； put / get ；add / delete ； lock / unlock ；open / close ； min / max ；old / new ； start / stop ；next / previou
20、s ；source / target ；show / hide ； send / receive ；source / destination ；cut / paste ；up / down正例：static final int MIN_WIDTH = 4;static final int MAX_WIDTH = 999;【规则 4-5】类名采用大小写结合的方法，构成类名的每个单词的首字母的首字母也必须大写。在构成类名的单词之间不用下划线。【规则 4-6】采用应用领域相关的术语来命名。【规则 4-7】程序中不要出现仅靠大小写区分的相似的标识符。【规则 4-8】用正确的反义词组命名具有互斥意义的变
21、量或相反动作的函数等。【规则 4-9】常量名都要使用大写字母 , 用下划线 _ 分割单词。软件编程规范Java 篇第 23 页 共 36 页static final int GET_THE_CPU = 1;说明：变量，尤其是局部变量，如果用单个字符表示，很容易出错（如 l 误写成 1）,而编译时又检查不出，则有可能增加排错时间。变量的命名应当选择精炼、意义明确的名字，才能简化程序语句，改善对程序功能的理解。正例： float myWidth;byte buffer;说明：这样容易区分一个控件的目的和它的类型，容易在一个表里找到各个控件。正例： btnOklistCustomernewFiles
22、说明：方法名力求清晰、明了，通过方法名就能够判断方法的主要功能。多个单词组合而成的方法名中，第一个单词后面的单词采用大小写字母结合的形式（首字母大写） ，但专有名词不受限制。单词间不用下划线连接。正例： getFirstName()getAccountNumber()isPersistent()isAtEnd()【规则 4-10】一般变量名不得取单个字符（如 i、j 、k 等）作为变量名，局部循环变量除外。【规则 4-11】变量名应该简短但意义完整，变量名的选择应该有助于记忆。【规则 4-12】控件命名应采用完整的英文描述符命名，名字的前缀是控件类型名。【规则 4-13】方法名应当能体现方法的
23、作用，必须用小写字母开头的单词组合而成，且应当使用“动词”或者“动词名词” （动宾词组） 。【规则 4-14】获取性方法的命名有两类，一种是判断性的操作（获取属性的状态，返回值为 boolean） ，如判断某些控件的状态等，对于这些操作，应当是以 is 为方法声明的开头。另外一种是获取返回值的操作，对一这种操作，应当以 get 开头。 【规则 4-15】属性设置性的方法命名以 set 开头，后紧跟属性名。软件编程规范Java 篇第 24 页 共 36 页说明：根据这个标准来命名一个类的方法，可以很容易的让人明白这个方法的基本功能。正例： setFirstName(String aName)se
24、tAccountNumber(int anAccountNumber)setReasonableGoals(Vector newGoals)setPersistent(boolean isPersistent)setAtEnd(boolean isAtEnd)说明：这些方法主要用来进行类型转换。正例： toString()说明：指定常量（final，static 变量）可以使得代码更容易被理解与维护。正例：class USNFixed private static final int ARRAY_SIZE = 1000;int getArray () return new int ARRAY_
25、SIZE; /正确说明：这样做的目的是为了代码的可重用性。【规则 4-16】To 型方法：表示类型转换的方法一般用 to 开头。建议 4-1避免直接使用数字常量 ，提高代码可读性。建议 4-2类提供 toString()方法，以方便调试。建议 4-3尽量避免名字中出现数字编号，如 value1、value2 等，除非逻辑上的确需要编号。建议 4-4标识符前最好不加项目、产品、部门的标识。软件编程规范Java 篇第 25 页 共 36 页正例： btnOpenNewFile控件常用缩略语如下：控件名称 控件缩略词JApplet apltJButton btnJCheckBoxMenuItem c
26、hkmiJColorChooser clrchrJDialog dlgJEditorPane edtpJFrame frmJInternalFrame ifrmJLabel lblJList lstJMenu muJMenuBar mubrJMenuItem muitmJPanel pnlJPasswordField pwdfldJPopupMenu ppmuJProgressBar prgbrJRootPane rtpnJScrollBar scrlbrJScrollPane scrlpnJSeparator sptJSlider sldJSplitPane spltpnJTabbedPan
27、e tbpnJTable tblJTextField txtfldJTextPane txtpnJToggleButton tglbtnJtoolTip tltpJtree trJviewport vwprtJwindow win建议 4-5对于界面控件名称比较长的，可用 “控件缩写+控件功能描述”的命名方式。软件编程规范Java 篇第 26 页 共 36 页5 声明正例：int level;int size;反例：int level, size;反例：void myMethod()boolean myFlag = false;myFlag = isVisible(myView) /作为可见性
28、判断标志/使用 myFlag 做其它操作myFlag = isEnable(myComponent) /作为可用性判断标志正例：void myMethod()int myInt = 0; /方法块的开始/其它语句【规则 5-1】一行只声明一个变量。【规则 5-2】一个变量有且只有一个功能，不能把一个变量用于多种用途。建议 5-1变量声明应该只放在代码段的开始部分。最好不要到使用时才声明变量。对象类变量在函数体结束后，手工设置为 null 值，以利于资源的回收。软件编程规范Java 篇第 27 页 共 36 页6 表达式与语句表达式是语句的一部分，它们是不可分割的。表达式和语句虽然看起来比较简单
29、，但使用时隐患比较多。本章归纳了正确使用表达式和 if、for 、while 、switch 等基本语句的一些规则与建议。说明：复杂的语句阅读起来难于理解，并容易隐含错误。正例：argv+; 反例：argv+; argc-;if(s4 = null) s4 = new String(“Joy”);说明：由于将运算符的优先级与结合律熟记是比较困难的，为了防止产生歧义并提高可读性，即使不加括号时运算顺序不会改变，也应当用括号确定表达式的操作顺序。正例：if (iYear % 4 = 0) .myMethod()if (condition)count = 1;【规则 6-1】每一行应该只包括一个语句
30、。【规则 6-2】在表达式中使用括号 ，使表达式的运算顺序更清晰。【规则 6-3】当复合语句作为控制流程的一部分时，应该用 把所有的复合语句括起来，即使只有一句简单语句。软件编程规范Java 篇第 28 页 共 36 页说明：无论是 float 还是 double 类型的变量，都有精度限制。所以一定要避免将浮点变量用“=”或“!=”与数字比较，应该转化成“=”或“= -EPSINON) case SPAN_OFF:处理语句break;default:处理语句break;说明：Java 编译器对 boolean 型变量在 if 条件语句中的赋值时合法的，对整型变量的赋值是不合法的。【规则 6-4
31、】不可将浮点变量用 “=”或“!=”与任何数字比较。【规则 6-5】在 switch 语句中，每一个 case 分支必须使用 break 结尾，最后一个分支必须是 default 分支。建议 6-1避免在“if”条件中赋值 。软件编程规范Java 篇第 29 页 共 36 页说明：除非有时不得不用括号使返回结构更加明显。正例：return;return myDisk.size();return (size ? size : defaultSize); /用括号使返回结构更加明显。说明：保持程序简洁。如果需要判断的条件较多，建议用临时布尔变量先计算是否满足条件。正例：boolean bCondi
32、tion;dobCondition = (tApiPortNo.bStateAcpActivity != PASSIVE)| (tApiPortNo.bStateLacpActivity != PASSIVE) 正例：for (iCol = 0; iCol 5; iCol+)for (iRow = 0; iRow 100; iRow+)iSum = iSum + aiDateiRowiCol;反例：建议 6-2带值的返回语句不需要用括号 （） 。建议 6-3循环嵌套次数不大于 3 次。建议 6-4do while 语句和 while 语句仅使用一个条件。建议 6-5在多重循环中，如果有可能，应当将最长的循环放在最内层，最短的循环放在最外层，以减少 CPU 跨切循环层的次数。软件编程规范Java 篇第 30 页 共 36 页for (iRow = 0; iRow 100; iRow+)for (iCol = 0; iCol 5; iCol+)iSum = iSum + aiDateiRowiCol;建议 6-6不可在 for 循环体内修改循环变量，防止 for 循环失去控制。
