JAVA编码规范v1.0

JAVA 编码规范编码规范 2011 6 20 北京信息技术开发公司 JAVA 编码规范 v1 0 2 16 目目 录 录 1导言 4 1 1目的 4 1 2范围 4 1 3角色和职责 4 1 4术语定义 4 2源代码要求 5 2 1可读性要求 5 2 2结构化要求 5 2 3正确性与容错性要求 5 2 4可重用性要求 6 2 5源代码管理 6 3格式 7 3 1缩进 7 3 2 间隔 8 3 3 空行 9 3 4 类成员的摆放顺序 9 3 5 文件格式 File Format 9 3 6 行最大长度 10 3 7 括号 10 4命名规则 11 4 1包 11 4 2类和接口 11 4 3方法 11 4 4get 和 set 方法 属性的定义 11 4 5变量 12 4 5 1普通变量 12 4 5 2常用对象变量 12 JAVA 编码规范 v1 0 3 16 4 5 3临时变量 13 4 5 4成员变量 13 5常量的命名 14 6注 释 15 6 1要求 15 6 2JavaDoc 说明 15 6 3类 16 6 4方法 16 JAVA 编码规范 v1 0 4 16 1导言导言 1 1 目的目的 本文档旨在提供一个编码的标准 以便所有 Java 代码在产生的一开始就能够在整个开发团 队中保持一致 从而能够更好的阅读和修改代码 1 2 范围范围 本文档适用于信息中心项目开发团队的所有成员 为了使项目的后期维护和修改变的容易 在每个项目开发中一定要遵守本文档中的规定术语定义 1 3 角色和职责角色和职责 编码负责人 本规范在具体项目中执行监督负责人 通过实施 Source Review 制度 编程 人员在完成自己的一个模块并提交测试前 由编码负责人进行 Source Review 不符合本编 程规约的程序一律打回 重新修改 即编码人你认为自己的程序没有任何的功能问题 编码人员 本规范的遵守者 1 4 术语定义术语定义 Logger 系统进行日志输出了类 为引用第三方 Apache Group 的输出类 具体用 法见 Log 输出规范的说明 JAVA 编码规范 v1 0 5 16 2源代码要求源代码要求 2 1 可读性要求可读性要求 可读性第一 在不严重影响系统性能的情况下要优先考虑程序的可读性 2 2 结构化要求结构化要求 1 禁止出现两条等价的支路 2 用 IF 语句来强调只执行两组语句中的一组 禁止 else break else continue 和 else return 3 用 CASE 实现多路分支 4 不使用复杂算数表达式 如 等符号在含两个算数项的表达式中使用 5 避免不必要的分支 6 不要轻易用条件分支去替换逻辑表达式 2 3 正确性与容错性要求正确性与容错性要求 1 程序首先是正确 其次是优美 2 每个开发人员要养成自我检查程序的习惯 将明显的错误码消除在交与测试之前 3 对与进行系统测试或者生产运行中的系统 修改前应考虑修改方案对系统其它部 分的影响 查找与对该修改处的所有引用 进行分析 4 所有变量必须在声明时初始化 5 对所有的用户输入 必须进行合法性检查 6 不要比较浮点数的相等 只能进行范围比较 如 10 0 0 1 1 0 不可靠 7 程序与环境或状态发生关系时 必须主动去处理发生的意外事件 如文件能否逻 辑锁定 打印机是否联机等 8 单元测试也是编程的一部份 提交联调测试的程序必须通过单元测试 JAVA 编码规范 v1 0 6 16 2 4 可重用性要求可重用性要求 1 重复使用的完成相对独立功能的算法或代码应抽象为公共函数或类 2 公共函数或类应考虑 OO 思想 减少外界联系 考虑独立性或封装性 3 公共函数或类应建立使用模板 4 公共类和公共函数必须有详细的文档 说明功能 用法及缺陷 5 程序编码力求简洁 结构清晰 避免太多的分支结构及太过于技巧性的程序 尽 量不采用递归模式 6 编写程序时 亦必须想好测试的方法 换句话说 单元测试 的测试方案应在程 序编写时一并拟好 7 程序中每个 block 的开头 及 必须对齐 嵌套的 block 每进一套 缩进一 个 tab TAB 为 4 个空格 block 类型包括 if for while do 等关键字引出的 8 对于比较大的函数 每个 block 和特殊的函数调用 都必须注明其功能 2 5 源代码管理源代码管理 所有源程序必须放入配置管理工具中进行管理 尤其要加强维护中的系统源代码管理 详细办法请遵守配置管理规范 JAVA 编码规范 v1 0 7 16 3格式格式 3 1 缩进缩进 所有的缩进皆为 4 个空格 对应的括号通常在同一列的位置上 例如 void foo while bar 0 Logger debug bar if oatmeal tasty Logger debug Oatmeal is good and good for you else if oatmeal yak Logger debug Oatmeal tastes like sawdust else Logger debug tell me pleeze what iz dis oatmeal switch suckFactor case 1 Logger debug This sucks break case 2 Logger debug This really sucks break default Logger debug whatever break 1 所有的缩进是由 Space 空格 键 形成的 而不是 Tab 键 JAVA 编码规范 v1 0 8 16 2 所有的 if while 和 for 语句中的 状态 内容必须用括号括起来 就算只有一个状态 if superHero theTick Logger debug Spoon 3 2 间隔间隔 1 所有的标识符都必须被空白字符包围 int theTick 5 if theTick 5 这么做唯一可能成为麻烦的是复杂的布尔分析影响了清晰度 例 if hero theTick if hero theTick start args 0 tens i 数组 习惯写法是在所 有数组名之后直接跟 上一个左方括号 args 0 tens I args 0 tens i 自加 自减运算符 习惯写法是在所 有一元运算符前面或 后面直接加上操作数 count i count i 造型运算符 习惯写法是所有 造型都不加空格 MyClass v get 3 MyClass v get 3 MyClass v get 3 JAVA 编码规范 v1 0 9 16 3 3 空行空行 应该时不时的在各方法之间加入一些空格行来分割大段的代码 还应该在方法与方法之间加入一两行的空格行 3 4 类成员的摆放顺序类成员的摆放顺序 class Order 1 final attributes 2 attributes 3 constructors 4 methods 必须保持 private 方法被放置在使用该方法的其他方法之上 而在构造器 constructor 之下 即使该构造器有可能调用这些 private 方法 3 5 文件格式文件格式 File Format package 必须总保持第一个出现 import 其次 再次 任何非 javadoc 的注释 然后是 javadoc 类文件 最后便是类 注意 一个文件 File 只能有一个类 内部类除外 示例 package misc import java io import this class does cool stuff author Joe Programmer class SpaceMonkey JAVA 编码规范 v1 0 10 16 3 6 行最大长度行最大长度 不要让一行代码的长度超过 120 个字符 最好是低于 80 个字符 如果代码开始向右延 伸得很长 你就应该考虑把它分割成更多的方法 3 7 括号括号 使用括号的目的必须是在表达上不但能够标明优先顺序 而且有助于使表达更简单明 了 另外 如果某一段代码有可能产生歧义 也需加括号 JAVA 编码规范 v1 0 11 16 4命名规则命名规则 所有的标识符只能用字母 A Z 或 a z 和数字 0 9 不能有货币符号或者其它非 ASCII 字符 4 1 包包 所有包名只能用小写字母 尽量别使包名长度超过 8 个字符 应该避免使用多个词作 为包名 示例 common core lang 4 2 类和接口类和接口 所有类和接口标识符将都使用混合 格 表示 每个名称中的每个单词首字母必须大写 同时这个名称的首字母也必须大写 其它的字母均小写 除了缩写词之外 它们必须全部 大写 示例 Customer SalesOrder TargetURL URLTarget 4 3 方法方法 1 类方法一般以动词开始 第一个字母小写 2 方法名中的每个词的第一个字母要大写 3 方法中的形参命名办法参见普通变量命名规则 4 4 get 和和 set 方法方法 属性的定义 属性的定义 用于设置对象状态的方法必须在方法名前面加一个前缀 set 用于检索一个布尔类型 对象状态的方法必须在方法名前面加一个前缀 is 而用于检索其它类型对象状态的方法则 必须在方法名前面加上 get 示例 JAVA 编码规范 v1 0 12 16 setEnabled getName isEnabled 4 5 变量变量 4 5 1普通变量普通变量 普通变量指的方法体中或者方法参数的变量 变量的命名应尽可能采用见名知义 基本命名规则如下 变量名变量名 变量前缀变量前缀 变量含义变量含义 变量前缀遵循匈牙利命名规则 定义如下 类型类型前缀前缀 shortshorts s intintn n charcharchch doubledoubled d booleanbooleanb b longlongl l floatfloatf f 4 5 2常用对象变量常用对象变量 类型类型前缀前缀 StringStringstrstr VectorVectorv v HashMapHashMaphmhm HashtableHashtablehtht DateDatedtdt TimestampTimestamptsts CollectionCollectioncollcoll JAVA 编码规范 v1 0 13 16 IteratorIteratoriteriter ListListlstlst Object Object aryObjaryObj 4 5 3临时变量临时变量 一般临时变量没有具体的意思 所以临时变量名为 临时变量名 变量前缀 Temp 或 Tmp 其中有一些 C 语言延续下来的常见临时变量也可以接受 如 i j k 一般用于表示一个 临时整型变量 4 5 4成员变量成员变量 无论是类成员变量是静态成员变量 都要在普通变量的命名规则基础上在加前缀 m 注意不可以使用 g JAVA 编码规范 v1 0 14 16 5常量的命名常量的命名 JAVA 中常量命名使用 Static Final 变量实现 常量名必须具有一定的实际意义 常量的名字必须都大写 每个单词之间用 连接 并且指出完整含义 常量声明在类的最上边 每一条定义必须有一简单的注释 说明其作用 JAVA 编码规范 v1 0 15 16 6注注 释释 大部分注释尽量用 对于所有的 javadoc 的注释则用 而临时对代码块 进行的注释尽量用 6 1 要求要求 1 类 方法 变量必须注释说明 注释内容应根据客户要求的语言进行 原则上 除常量 变量 变量类型等以外的说 明尽可能采用中文注释 2 保持注释与代码一致 6 2 JavaDoc 说明说明 1 JavaDoc 注释将用于说明那些被其它类调用的类 属性和方法 这些注释必须出现在 所要说明的各项之前 2 JavaDoc 注释一般不会用于说明一些显而易见的方法 例如 public static void main String args 或 public int getX 3 JavaDoc 注释也不用于说明一些显而易见的参数 如 public void setX int newX 4 诸如 servlet 和 EJB 等那些没有被其它类调用的类 也不必加 JavaDoc 注释 把源码上交给整个团队之前 必须先经过 JavaDoc 处理 并全面检查处理结果 以确定说 明文字确实可读而且清楚明白 示例 Copyright 2011 hongxin Change Revision Date Author Remarks date user create author xxx xxx version 创建时间 Jan 11 2011 2 56 39 PM 类说明 xxxxx JAVA 编码规范 v1 0 16 16 6 3 类类 每个类都要有类说明 类的 JavaDoc 说明文件必须包括以下内容 1 简要的提纲 2 详细的描述 3 使用该类的示例代码段 4 用 author 标签列出作者 注意 由于 JavaDoc 中一个 功能 feature 限制 所有示例代码的每行前面必须加入一 个星号 以便保存每行的缩进 例如 类注释 author user version 创建时间