java编码书写规范.doc

万洲科技有限公司万洲科技有限公司万洲科技有限公司万洲科技有限公司 JavaJavaJava 编码书写规范 编码书写规范 编码书写规范 编码书写规范 v1 0v1 0v1 0 万洲科技有限公司万洲科技有限公司 2010 年年 4 月月 Java 编码书写规范 I 目目 录录 1 命名约定命名约定1 1 1 一般概念一般概念1 1 2 示范示范1 2 注释约定注释约定4 2 1 一般概念一般概念4 2 2 示范示范4 2 3 注释范围注释范围5 3 文件样式约定文件样式约定5 3 1 JAVA JAVA 5 3 1 1 版权信息6 3 1 2 PACKAGE IMPORTS6 3 1 3 CLASS6 3 1 4 CLASS FIELDS7 3 1 5 构造函数8 3 1 6 克隆方法8 3 1 7 类方法 类的普通成员函数 9 3 1 8 TOSTRING 方法9 3 1 9 MAIN 方法9 3 2 JAVA SERVER PAGE JSP 9 3 2 1 版本信息10 3 2 2 TAG10 3 2 3 值输出11 3 2 4 嵌入代码段11 4 其它代码书写风格约定其它代码书写风格约定11 4 1 文档自动生成文档自动生成11 4 2 缩进缩进12 4 3 页宽页宽12 4 4 变量声明变量声明14 4 5 变量初始化变量初始化14 4 6 局部变量声明局部变量声明14 4 7 空行空行14 4 8 大括号大括号 15 4 9 小括号 小括号 15 Java 编码书写规范 II 4 10 运算符运算符15 4 11 参数间隔参数间隔15 4 12 JSP 文件命名文件命名16 4 13 SERVLET类命名 待定 类命名 待定 16 5 编码指南编码指南16 5 1 对实例以及类变量的访问控制对实例以及类变量的访问控制16 5 2 引用类变量和类方法引用类变量和类方法16 5 3 常量常量17 5 4 变量赋值变量赋值17 5 5 5 5 其它惯例其它惯例18 5 5 1 圆括号18 5 5 2 返回值18 5 5 3 条件运算符 前的表达式19 5 5 4 特殊注释19 5 5 5 异常使用原则19 Java 编码书写规范 1 1 命名约定命名约定 除了以下几个特例之外 命名时必须始终采用完整的英文描述符 此外 一般应采用小写字母 但类名 接口名以及任何非初始单词的第一个字母要大 写 1 1 一般概念一般概念 尽量使用完整的英文描述符 采用适用于相关领域的术语 采用大小写混合使名字可读 尽量少用缩写 但如果用了 要明智地使用 且在整个工程中统一 避免使用长的名字 尽量小于 25 个字母 避免使用类似的名字 或者仅仅是大小写不同的名字 避免使用下划线 除静态常量等 1 2 示范示范 包 Package 采用完整的英文描述符 应该都是由小写字母组成 格式 为 com wzsoft 如 com wzsoft web com wzsoft action com wzsoft model com wzsoft manager com wzsoft manager impl 类 Class 采用完整的英文描述符 所有单词的第一个字母大写 在上 下文语境允许的情况下 可以使用缩略词 但必须保证整个开发小组的一致性 比如 number 可缩写为 num 如 Java 编码书写规范 2 Customer SavingsAccount 接口 Interface 采用完整的英文描述符说明接口封装 所有单词的第一 个字母大写 在接口名称的最前面使用大写的 I 表明这是一个接口 习惯上 名字后面加上后缀 able ible 或者 er 但这不是必需的 如 IContactable IPrompter 组件 部件 Component 使用完整的英文描述来说明组件的用途 前端加 上组件类型 如 btnOK lstCustomer menuFile 异常 Exception 采用异常类型的各单词首字母表示异常 如 Excpetion e IOException ioe 字段 属性 字段采用完整的英文描述 第一个字母小写 任何中间单词的 首字母大写 firstName lastName 实参 参数 同字段 属性的命名规则 public void setFirstName String firstName this firstName firstName Java 编码书写规范 3 局部变量 同字段 属性的命名规则 获取成员函数 被访问字段名的前面加上前缀 get getFirstName getLastName 布尔型的获取成员函数 所有的布尔型获取函数必须用单词 is 做前缀 isPersistent isString 设置成员函数 被访问字段名的前面加上前缀 set setFirstName setLastName setWarpSpeed 普通成员函数 采用完整的英文描述说明成员函数功能 第一个单词尽可能 采用一个动词 第一个字母小写 openFile addAccount 静态常量字段 static final 全部采用大写字母 单词之间用下划线分隔 MIN BALANCE DEFAULT DATE 循环计数器 通常采用字母 i j k m n 或者 counter 都可以接受 i j k m n counter 数组应该总是用下面的方式来命名 objectType variant 不得使用 objectType variant 方式 Java 编码书写规范 4 int arrInt String args 对象实例 同组件 部件 byte arrBuffer StringBuffer sbContent 2 注释约定注释约定 2 1 一般概念一般概念 注释应该增加代码的清晰度 保持注释的简洁 在写代码之前写注释 注释出为什么做了一些事 而不仅仅是做了什么 2 2 示范示范 文档注释 在紧靠接口 类 成员函数和字段声明的前面注释它们 客户 客户是我们将服务和产品卖给的人或机构 String customer C 语言风格注释 采用 C 语言风格的注释去掉不再使用但你仍想保留的代 码 仍想保留是因为用户万一会改变想法 或者在调试过程中想让它暂时失效 这部分代码因为已被它之前的代码取代 由 B Gustafsson 于 1999 年 6 月 4 日注释掉 如果两年之后还未使用 将 其删除 源代码 单行注释 在成员函数内采用单行注释 来说明业务逻辑 代码段和暂时变 量的声明 注释符 后必须紧跟一个空格 然后才是注释信息 Java 编码书写规范 5 遵照 Sarek 的规定 给所有 超过 1000 的发货单 打 5 的折扣 让利活 动于 1995 年 2 月开始 if condition 处理条件 即约定主要的说明性注释使用文档注释 C 风格注释只用来标注过期不用 的代码 单行注释用来标注一些简单却容易混淆的逻辑 比较长的单独作为一 行 较简洁的可以放在代码行尾 2 3 注释范围注释范围 类 类的目的 即类所完成的功能 注释出采用的变量 接口 注释描述设置接口的目的 它应如何被使用 成员函数 对于设置与获取成员函数 在成员变量已有说明的情况下 可 以不加注释 普通成员函数注释要求说明完成什么功能 参数含义及返回什么 普通成员函数内部控制结构 注释代码做了些什么以及为什么这样做 处 理顺序等 实参 参数 注释参数含义 及其它任何约束或前提条件 字段 属性 注释字段的描述 局部变量 无特别意义的情况下不加注释 3 文件样式约定文件样式约定 3 1 Java java 所有的 Java java 文件都必须遵守如下的样式规则 Java 编码书写规范 6 3 1 1 版权信息版权信息 版权信息必须在 java 文件的开头 比如 Copyright 2009 Wat Soft Co Ltd All right reserved Author Date 2009 02 27 作者名称要用中文 其他不需要出现在 javadoc 的信息也可以包含在这里 3 1 2 Package Imports package 行要在 import 行之前 import 中标准的包名要在本地的包名之 前 而且按照字母顺序排列 如果 import 行中包含了同一个包中的不同子目 录 则应该用 来处理 package stats import java io import java util Observable import hotlava util Application 这里 java io 是用来代替 InputStream and OutputStream 的 3 1 3 Class 类的注释 Title 文件名称 Java 编码书写规范 7 Description 类内容的简介 更新记录 格式 更新日期 修改的版本 操作人 内容 2005 06 28 1 0 张三 完善 create 方法 Copyright Copyright c 2009 Company Wat Soft Co Ltd version 1 1 类定义 包含了在不同行的 extends 和 implements public class CounterSet extends Observable implements Cloneable 3 1 4 Class Fields 类的成员变量 Packet counters protected int packets public 的成员变量必须生成文档 JavaDoc proceted private 和 package 定义的成员变量如果名字含义明确的话 可以没有注释 类变量的存取 如类的成员变量已经有注释 类变量的存取方法可以没有 注释 public int getPackets return this packets Java 编码书写规范 8 public void setPackets int packets this packets packets 3 1 5 构造函数构造函数 构造函数 应该用递增的方式写 比如 参数多的写在后面 public CounterSet this size 100 public CounterSet int size this size size 3 1 6 克隆方法克隆方法 如果这个类是可以被克隆的 那么下一步就是 clone 方法 public Object clone try catch CloneNotSupportedException e 3 1 7 类方法类方法 类的普通成员函数 类的普通成员函数 类的方法 Java 编码书写规范 9 Set the packet counters param r1 param r2 protected final void setArray int r1 int r2 int r3 int r4 throws IllegalArgumentException Ensure the arrays are of equal size 3 1 8 toString 方法方法 一般情况下 每一个类都应该定义 toString 方法 public String toString 3 1 9 main 方法方法 普通类 考虑置入一个 main 方法 其中包含用于测试那个类的代码 如 果包含了 main 方法 那么它应该写在类的底部 3 2 Java Server Page jsp 所有的 Jsp jsp 文件都必须遵守如下的样式规则 3 2 1 版本信息版本信息 文件开头应有一个文件的版本注释 格式为 Java 编码书写规范 10 3 2 2 tag 关键 tag 的书写顺序为 注意事项 使用国标扩展字符集 GBK 作为 content 的 charset contentType 在被包含的文件一定不能写 而其他文件一定要写 建议用以下两种格式 Java 编码书写规范 11 tag 一律用小写 属性的值用双引号引起来 出错信息定向到公用的出错页面 JSP 页面与 java 编码要完全分离 待补充 3 2 3 值输出值输出 输出值时使用 3 2 4 嵌入代码段嵌入代码段 使用单独行 结尾 注释参见 2 代码块缩进参 见 4 2 for int i 0 i 4 其它代码书写风格约定其它代码书写风格约定 4 1 文档自动生成文档自动生成 必须用 javadoc 来为类生成文档 不仅因为它是标准 这也是被各种 java 编译器都认可的方法 使用 author 标记是不被推荐的 因为代码不应该是被 个人拥有的 Java 编码书写规范 12 4 2 缩进缩进 缩进是必须的 并且在同一系统所有编码的缩进风格必须是统一的 4 3 页宽页宽 页宽应该设置为 80 字符 源代码不能超过此宽度 在任何情况下 超长 的语句应该在一个逗号或者一个操作符后折行 一条语句折行后 应该比原 来的语句再缩进 3 个字符 当一个表达式无法容纳在一行内时 可以依据如下一般规则断开之 在一个逗号后面断开 在一个操作符前面断开 宁可选择较高级别 higher level 的断开 而非较低级别 lower level 的断 开 新的一行应该与上一行同一级别表达式的开头处对齐 如果以上规则导致你的代码混乱或者使你的代码都堆挤在右边 那就 代之以缩进 8 个空格 以下是两个断开算术表达式的例子 前者更好 因为断开处位于括号表达 式的外边 这是个较高级别的断开 longName1 longName2 longName3 longName4 longName5 4 longname6 参考 longName1 longName2 longName3 longName4 longName5 4 longname6 避免 以下是两个缩进方法声明的例子 前者是常规情形 后者若使用常规的缩 进方式将会使第二行和第三行移得很靠右 所以代之以缩进 8 个空格 常规缩进 someMethod int anArg Object anotherArg String yetAnotherArg Object andStillAnother Java 编码书写规范 13 制表符缩进 private static synchronized horkingLongMethodName int anArg Object anotherArg String yetAnotherArg Object andStillAnother if 语句的换行通常使用 8 个空格的规则 因为常规缩进 4 个空格 会使语 句体看起来比较费劲 比如 不要用这种方式 if condition1 用这种方式 if condition1 或者这种方式 if condition1 这里有三种可行的方法用于处理三元运算表达式 alpha aLongBooleanExpression beta gamma alpha aLongBooleanExpression beta Java 编码书写规范 14 gamma alpha aLongBooleanExpression beta gamma 4 4 变量声明变量声明 必须一行一个声明 因为这样以利于写注释 亦即 int level 标识层级别 int size 表大小 要优于 int level size 4 5 变量初始化变量初始化 尽量在声明局部变量的同时初始化 唯一不这么做的理由是变量的初始值 依赖于某些先前发生的计算 4 6 局部变量声明局部变量声明 只在代码块的开始处声明变量 一个块是指任何被包含在大括号 和 中间的代码 不要在首次用到该变量时才声明之 4 7 空行空行 空行将逻辑相关的代码段分隔开 以提高可读性 下列情况应该总是使用两个空行 一个源文件的两个片段 section 之间 类声明和接口声明之间 下列情况应该总是使用一个空行 两个方法之间 方法内的局部变量和方法的第一条语句之间 Java 编码书写规范 15 一个方法内的两个逻辑段之间 用以提高可读性 4 8 大括号大括号 中的语句应该单独作为一行 例如 if i 0 i 4 9 小括号 小括号 左括号和后一个字符之间不应该出现空格 同样 右括号和前一个字符 之间也不应该出现空格 例如 CallProc AParameter 不符合规范 CallProc AParameter 符合规范 不要在语句中使用无意义的括号 括号只应该为达到某种目的而出现在源 代码中 4 10 运算符运算符 每个运算符与两边的字符之间都应该有一个空格 int num 100 符合规范 num 1 符合规范 num num 1 不符合规范 应该是 num num 1 4 11 参数间隔参数间隔 多个参数之间的 应紧跟前面的参数 与后面的参数之间有一个空格 public int max int a int b int c 符合规范 return Math max Math max a b c 不符合规范 a 后面应该由空格 b 和 c 的前面也应该由空格 Java 编码书写规范 16 4 12 JSP 文件命名文件命名 采用完整的英文描述说明 JSP 所完成的功能 尽可能包括一个动词 第一 个字母小写 如 viewMessage jsp editUser jsp 或者 forumChooser jsp 等 4 13 Servlet 类命名 待定 类命名 待定 一般对应于所服务的对象加后缀 Service 来命名 如 UserService TradeService 等 5 编码指南编码指南 5 1 对实例以及类变量的访问控制对实例以及类变量的访问控制 若没有足够理由 不要把实例或类变量声明为公有 所有类成员变量要通 过方法访问 通常 实例变量无需显式的设置 set 和获取 gotten 通常这作为 方法调用的边缘效应 side effect 而产生 一个具有