Java代码书写规范(高手必经之路).doc

u 符号命名规则符号名包括：模块名，变量名，常量名，方法（函数/子程序）名,数据区名,缓冲区名等。符号命名通常应遵循以下规则：通用规则：1、在所有命名中，都应使用标准的英文单词或缩写。不得使用拼音或拼音缩写，除非该名字描述的是中文特有的内容，如半角、全角, 声母、韵母等。 2、所有命名都应遵循达意原则，即名称应含义清晰、明确。 3、所有命名都不易过长，应控制在规定的最大长度以内。 4、所有命名都应尽量使用全称。 5、如果命名使用缩写，则必须对其进行注释和说明。 具体规范： 1、工程名 统一制订。 2、文件名文件名应与类名相同，这是java的规范3、方法名/函数名 方法名第一个单词小写。 推荐使用动宾结构。方法名应清晰反映该方法的功能、用途。 方法名最长不得超过30个字符。 例： getCollection(); setCollection(); insertObject(); deleteObject();3、变量名必须使用有意义的变量名。推荐的类型缩写（type）char：chboolean：bint：ilong：ldouble：dfloat：f 变量名最长不得超过20个字符。 4、类名 必须以大写字母开头，类名反映具体含义，以清晰表达类的用途和功能为原则 当名称由多个单词构成时，每一个单词的第一个字母必须大写u 代码书写规范 书写规范即在编写代码过程中所使用的标准格式， 主要包括空格的使用、括号的使用、缩近格式和其他一些内容。源代码书写规范1在.java/.jsp的开头应有一段格式统一的说明，内容包括： a. 文件名 (Title/FileName)； b. 创建人 (Author)； c. 文件创建时间 (Date)； d. 简短说明文件功能、用途 (Description /Function)。 样例：/* * 标题:Schedule.java * 描述:用来实现计划项目审批 * 创建:2001-06-30 * 作者:赵文正 * 详细：详细描述计划项目审批的细节,如何根据细节功能确定方法 */2. 除非极其简单，否则对函数应有注释说明。内容包括：功能、入口/出口参数，必要时还可有备注或补充说明。 3. 每行代码的长度推荐为80列，最长不得超过120列；折行以对齐为准。 4. 在类的成员函数内调用其他类的成员函数时，其他类的成员函数可做简短说明。 6. 函数入口参数有缺省值时，应注释说明。 例: float getValue(int ID, boolean flag) /* parameter description ID: Identify No flag : default = TRUE */ 7. else if 必须写在一行。 8. 与、有关的各项规定： 、应独占一行。在该行内可有注释。 例：正确： for (i = 0; i Line; i+) / . System.out.println(Line=+ i+” value = ”+Linesi); 不得写做： for (i = 0; i 0) m = 1; n+; 不得写做： if (i 0) m = 1; n+; 在循环、分支之后若只有一行代码，虽然可省略、，但不推荐这么做。若省略后可能 引起歧义，则必须加上、。例：正确： if (n = -2) n = 1; else if (n != nTemp) n = 2; else n = 3; 不得写做： if (n = -2) n = 1; else if (n != nTemp) n = 2; else n = 3;9. 与空格有关的各项规定。 所有两目、三目运算符的两边都必须有空格。在单目运算符两端不必空格。但在 .、等运算符前后，及&（取地址）等运算符之后不得有空格。例：正确： int n = 0, nTemp; for (int i = nMinLine; i = nMaxLine; i+)不得写做： int n=0, nTemp; for ( int i=nMinLine; i=nMaxLine; i+ ) or、while、if 等关键词之后应有1个空格，再接(，之后无空格；在结尾的)前不得有空格。例：正确： if (-2 = n)不得写做： if(-2 = n)或 if ( -2 = n )等等。 调用函数时，(、)前后不得有空格。 类型强制转换时，()前后不得有空格 10. 与缩进有关的各项规定缩进以 Tab 为单位。1 个 Tab 为 4 个空格 下列情况，代码缩进一个 Tab:函数体相对函数名及、。 if、else、for、while、do 等之后的代码。 一行之内写不下，折行之后的代码，应在合理的位置进行折行。若有 + - * / 等运算符，则运算符应在上一行末尾，而不应在下一行的行首。 下列情况，不必缩进：switch 之后的 case、default。在switch-case结构中，case语句距离switch 语句的开始应缩进一个TAB，每个case的程序体距离case的开始缩进一个TAB; 举例： switch (value) case 1: /* Body for case 1. */ break; case 2: /* Body for case 2. */ break; default: /* Body for default. */ break; 所有的函数定义和函数定义的花括号都应位于第一列； 所有成对的花括号都应出现在同一列，并与相应的控制语句同列，在对数组、类、和枚举类型的成员初始化时，同样遵循此规则； 对于java/jsp程序，强烈建议使用如下结构： try catch(Exception ex) finally try catch (Exception e) 其他 对复杂的条件语句（分支中的语句较多），应在每个结束的花括号后加一条注释说明是哪一个分支的结束，并在分支的开始加注释说明进入分支的条件；复杂的循环程序段遵循此规则； 每个语句占一行； 函数定义时，函数的返值和函数名应在同一行。u 程序的注释规范在项目开发过程中，对代码的注释十分重要，与代码规范一样提供良好的可读性和易维护性，对程序中的每一个文件、类、函数以及重要的变量，都应用相关的注释说明他们的作者、用途和使用方法，对程序中较复杂或重要的部分应说明它们的含义和目的，对后续添加和修改的部分应注明修改者姓名和修改时间。 SUN提供了JavaDoc工具抽取程序中的相关注释：以下都以SUN 的标准（即：JAVA API 规定式样的注释）来说明程序的注释规范，以利于根据程序的注释用Javadoc生成API格式的java 文档。原则： 注释是程序调用者和执行者之间唯一的协议 程序异常的注释必须显著的标明注释 程序的注释应该能提供足够的信息，根据注释，质量保证人员应该能够写出测试用例Javadoc 能够根据以下几类文件中的注释抽取出来生成JAVA API格式的注释： Java源程序，包括 源程序，接口，结构的注释 包的注释文件 一般的注释文件 其它文件：包括 类文件，applet, HTML等文档注释的一般格式文档的注释通常包括两部分。描述部分和 0 到多个标记。其格式如下例： /* * This is the description part of a doc comment * * tag Comment for the tag*/注：行的长度不超过80个字符 如果有一段以上的注释，要使用进行分段。注释的检查工具SUN提供DocCheck工具，用来检查注释风格和标记的错误，并能提供修改建议。描述部分描述部分第一句应该是关于该类，接口，包，成员的概括，Javadoc 工具将会copy这一句作为该部分的概括。例： /* * This is a simulation of Prof. Knuths MIX computer. */Javadoc会抽取到Prof为止，作为概述。不过可以通过 HTML标记 & or 来连接连个句子。例如 /* * This is a simulation of Prof. Knuths MIX computer. */或者 /* * This is a simulation of Prof. Knuths MIX computer.*/以下情况可以不用写注释，Javadoc会自动生成相应的注释 当一个类的方法重载超类的方法时； 当一个接口中的方法继承父接口中的方法时； 当在类中实现该类继承的接口的方法的时候；推荐的风格使用.来标记关键字或重要的名称，如：java关键字，包名称，类名称，方法名称，接口名称，代码样例等。使用内嵌的链接link来引起超连结建议使用短语代替句子，特别是在param 标记描述的时候在描述部分中尽量是用第三人称而不是第二人称进行描述，例如： Gets the label. (首选格式) Get the label. (避免格式) 在描述是尽量是用动宾结构 Gets the label of this button. (首选格式) This method gets the label of this button. (避免格式) 避免使用拉丁语，例如：应该用for example取代 e.g., 用that is 或者to be specific 代替 i.e.等等。标记惯例java规定1.0版规定了一下描述标记* author (类和接口中必须使用此标记)* version (类和接口中必须使用此标记) * param (只在方法和结构中使用)* return (只在方法中使用)* exception (如 throws一样，用来表示抛出异常)，例如： /* * throws IOException If an input or output exception occurred */ public void f() throws IOException / body * see （用来指出参考的部分）* since （开始版本）例：/* * since 1.2 */* serial (等同于serialField 或 serialData表示持续时间)* deprecated (不赞成使用 )，例：/* deprecated As of JDK 1.1, replaced by setBounds* see #setBounds(int,int,int,int)*/以上标记如果有多个的话，通常按照字母顺序列出，例如：see #field see #Constructor(Type, Type.) see #Constructor(Type id, Type id.) see #method(Type, Type,.) see #method(Type id, Type, id.) see Class see Class#field see Class#Constructor(Type, Type.) see Class#Constructor(Type id, Type id) see Class#method(Type, Type,.) see Class#method(Type id, Type id,.) see package.Class see package.Class#field see package.Class#Constructor(Type, Type.) see package.Class#Constructor(Type id, Type id) see package.Class#method(Type, Type,.) see package.Class#method(Type id, Type, id) see package 关于java标记基本原则更为详细的说明可见: Javadoc Reference page程序异常的注释所有检查过（catch）异常必须注释未检查的（RuntimeException）但调用的时候可能出现的异常，可适当的进行注释。包级的注释javadoc能够根据包的注释文件生成包的概述文件.其过程如下 package.html - package-summary.html(source file) javadoc (destination file)Copy 注释文件中 和 之间的内容作为最为包的概述放入package-summary.html 文件. 处理注释文件中出现的 see, since or link 等Javadoc 标记Copy 第一句作为总体概述（OverviewSummary）关于package.html的写法，通常有以下2种：空的包级注释模板，参考：Empty Template for Package-Level Doc Comment File常用的模板格式如下：第一句应该是关于包的概述. 如: Provides classes and interfaces for handling text, dates, numbers and messages in a manner independent of natural languages. 说明包的内容和目的 包的规定包括整个包的规定. 例如, java.awt 包应该描述该包在不同操作系统(Windows, Solaris, Mac)下的一般规定和行为. 包括链接到没出现在javadoc产生的文档中的声明。包括该规定的一些参考 相关的文档 包括未出现在规定中的申明，如样例，向导，演示程序等 类和接口的说明 Omit this section until we implement category tag 说明类和接口的逻辑分组 see 指出供参考的其他类，包，接口等内部类的注释关于内部类的注释通常如下例：/* * The method used for creating the tree. Any structural modifications * to the display of the Jtree should be done by overriding this method. * This method adds an anonymous TreeSelectionListener to the returned JTree. * Upon receiving TreeSelectionEvents, this listener calls refresh with * the selected node as a parameter. */ public JTree makeTree(AreaInfo ai) 注释样例以下是SUN提供的注释样例，以供参考/* * Graphics is the abstract base class for all graphics contexts * which allow an application to draw onto components realized on * various devices or onto off-screen images. * A Graphics object encapsulates the state information needed * for the various rendering operations that Java supports. This * state information includes: * * The Component to draw on * A translation origin for rendering and clipping coordinates * The current clip * The current color * The current font * The current logical pixel operation function (XOR or Paint) * The current XOR alternation color * (see setXORMode) * * * Coordinates are infinitely thin and lie between the pixels of the * output device. * Operations which draw the outline of a figure operate by traversing * along the infinitely thin path with a pixel-sized pen that hangs * down and to the right of the anchor point on the path. * Operations which fill a figure operate by filling the interior * of the infinitely thin path. * Operations which render horizontal text render the ascending * portion of the characters entirely above the baseline coordinate. * * Some important points to consider are that drawing a figure that * covers a given rectangle will occupy one extra row of pixels on * the right and bottom edges compared to filling a figure that is * bounded by that same rectangle. * Also, drawing a horizontal line along the same y coordinate as * the baseline of a line of text will draw the line entirely below * the text except for any descenders. * Both of these properties are due to the pen hanging down and to * the right from the path that it traverses. * * All coordinates which appear as arguments to the methods of this * Graphics object are considered relative to the translation origin * of this Graphics object prior to the invocation of the method. * All rendering operations modify only pixels which lie within the * area bounded by both the current clip of the graphics context * and the extents of the Component used to create the Graphics object. * * author Sami Shaio * author Arthur van Hoff * version %I%, %G% * since JDK1.0 */public abstract class Graphics /* * Draws as much of the specified image as is currently available * with its northwest corner at the specified coordinate (x, y). * This method will return immediately in all cases, even if the * entire image has not yet been scaled, dithered and converted * for the current output device. * * If the current output representation is not yet complete then * the method will return false and the indicated link ImageObserver * object will be notified as the conversion process progresses. * * param img the image to be drawn * param x the x-coordinate of the northwest corner of the * destination rectangle in pixels * param y the y-coordinate of the northwest corner of the * destination rectangle in pixels * param observer the image observer to be notified as more of the * image is converted. May be null * return true if the image is completely * loaded and was painted successfully; * false otherwise. * see Image * see ImageObserver * since JDK1.0 */ public abstract boolean drawImage(Image img, int x, int y, ImageObserver observer); /* * Dispose of the system resources used by this graphics context. * The Graphics context cann