Java 语言编码规范

Java 语言编码规范语言编码规范 Java 语言编码规范 第 2 页 目目 录录 一 规范简介 1 1 目的 1 2 范围 1 3 参考文档 1 4 说明 1 二 JAVA 编码规范 1 2 缩进排版 INDENTATION 2 2 1 行长度 Line Length 2 3 注释 COMMENTS 2 4 声明 DECLARATIONS 3 4 1 每行声明变量的数量 Number Per Line 3 4 2 初始化 Initialization 3 5 空白 WHITE SPACE 3 5 1 空行 Blank Lines 3 5 2 空格 Blank Spaces 4 6 命名规范 NAMING CONVENTIONS 4 7 性能考虑 5 7 1 使用 StringBuffer 对象 5 7 2 可移植性 5 7 3 换行 5 7 4 PrintStream 6 三 JSP 编码规范 6 四 SERVLET 编码规范 7 五 JSP 和 SERVLET 编程注意事项 7 六 代码范例 CODE EXAMPLES 7 Java 语言编码规范 第 1 页 一 一 规范简介规范简介 1 1 目的目的 制订本规范的目的是为培养规范设计和编程 养成良好的习惯 增强 JAVA 类软件产品 的稳定 健壮 可靠性 同时也为提高软件的可读性 可以让程序员尽快而彻底地理解新的 代码 使产品可维护性提高而制定的强制性规范 同时也是代码复审的依据 2 2 范围范围 本规范适用于公司 JAVA 类代码 包括 JSP 的代码编写标准 适用于代码编写阶段和代 码维护阶段 3 3 参考文档参考文档 SUN JAVA 代码编写规范 4 说明说明 本文档包括 java 编码规范 jsp 编码规范 servlet 编码规范 struts 代码规范请参阅 struts 编码规范 doc 二 二 javajava 编码规范编码规范 1 1 1 1 1 1 开头注释开头注释 Beginning Beginning Comments Comments 所有的源文件都应该在开头有一个 Java 语言风格的注释 其中列出标题 描述 日期 和版权声明 Title 标题 Description 描述 Copyright Copyright c 2007 Company 华胜天成 author 张三 version 1 0 Java 语言编码规范 第 2 页 1 1 2 1 1 2 包和引入语句包和引入语句 Package Package andand ImportImport Statements Statements 在多数 Java 源文件中 第一个非注释行是包语句 在它之后可以跟引入语句 例如 package java awt import java awt peer CanvasPeer 注 避免使用以下方式 import java awt 2 2 缩进排版缩进排版 Indentation Indentation 4 个空格常被作为缩进排版的一个单位 缩进的确切解释并未详细指定 空格 vs 制表 符 一个制表符等于 8 个空格 而非 4 个 2 1 2 1 行长度行长度 Line Line Length Length 尽量避免一行的长度超过 80 个字符 因为很多终端和工具不能很好处理之 注意 用于文档中的例子应该使用更短的行长 长度一般不超过 70 个字符 3 3 注释注释 Comments Comments Java 程序原有两类注释 实现注释 implementation comments 和文档注释 document comments 我们自己又增加了一种注释叫标记注释 实现注释是那些在 C 中见过的 使用 和 界定的注释 文档注释 被称为 doc comments 是 Java 独有的 并由 界定 文档注释可以 通过 javadoc 工具转换成 HTML 文件 实现注释用以注释代码或者实现细节 文档注释从实现自由 implementation free 的 角度描述代码的规范 它可以被那些手头没有源码的开发人员读懂 注释应被用来给出代码的总括 并提供代码自身没有提供的附加信息 注释应该仅包含 与阅读和理解程序有关的信息 例如 相应的包如何被建立或位于哪个目录下之类的信息不 应包括在注释中 在注释里 对设计决策中重要的或者不是显而易见的地方进行说明是可以的 但应避免 提供代码中己清晰表达出来的重复信息 多余的的注释很容易过时 通常应避免那些代码更 新就可能过时的注释 注意 Java 语言编码规范 第 3 页 频繁的注释有时反映出代码的低质量 当你觉得被迫要加注释的时候 考虑一下重写代 码使其更清晰 注释不应写在用星号或其他字符画出来的大框里 注释不应包括诸如制表符和回退符之 类的特殊字符 总之 注释要明确注明文件 页面 函数 算法之功能 用途 以及创建 修改信息等 4 4 声明声明 Declarations Declarations 4 1 4 1 每行声明变量的数量每行声明变量的数量 Number Number PerPer Line Line 推荐一行一个声明 因为这样以利于写注释 亦即 int level indentation level int size size of table 要优于 int level size 不要将不同类型变量的声明放在同一行 例如 int foo fooarray WRONG 注意 上面的例子中 在类型和标识符之间放了一个空格 另一种被允许的替代方式是使用 制表符 intlevel indentation level intsize size of table ObjectcurrentEntry currently selected table entry 4 2 4 2 初始化初始化 Initialization Initialization 尽量在声明局部变量的同时初始化 唯一不这么做的理由是变量的初始值依赖于某些先 前发生的计算 5 5 空白空白 White White Space Space 5 1 5 1 空行空行 Blank Blank Lines Lines 空行将逻辑相关的代码段分隔开 以提高可读性 下列情况应该总是使用两个空行 一个源文件的两个片段 section 之间 类声明和接口声明之间 Java 语言编码规范 第 4 页 下列情况应该总是使用一个空行 两个方法之间 方法内的局部变量和方法的第一条语句之间 一个方法内的两个逻辑段之间 用以提高可读性 5 2 5 2 空格空格 Blank Blank Spaces Spaces 下列情况应该使用空格 操作符之间应该有空格 6 6 命名规范命名规范 Naming Naming Conventions Conventions 命名规范使程序更易读 从而更易于理解 它们也可以提供一些有关标识符功能的信息 以助于理解代码 例如 不论它是一个常量 包 还是类 标识符类型命名规则例子 包 Packages 一个唯一包名的前缀总是全部小写的 ASCII 字母 并且是一个顶级域名 通常是 com edu gov mil net org 或 1981 年 ISO 3166 标准所指定的标识国家的英文双字符 代码 包名的后续部分根据不同机构各自内部的 命名规范而不尽相同 这类命名规范可能以特定 目录名的组成来区分部门 department 项目 project 机器 machine 或注册名 login names com sun eng com apple quicktime v2 edu cmu cs bovik cheese 类 Classes 命名规则 类名是个一名词 采用大小写混合的 方式 每个单词的首字母大写 尽量使你的类名 简洁而富于描述 使用完整单词 避免缩写词 除非该缩写词被更广泛使用 像 URL HTML class Raster class ImageSprite 接口 Interfaces 命名规则 大小写规则与类名相似 interface RasterDelegate interface Storing 方法 Methods 方法名是一个动词 采用大小写混合的方式 第 一个单词的首字母小写 其后单词的首字母大写 run runFast getBackground 变量 Variables 除了变量名外 所有实例 包括类 类常量 均 采用大小写混合的方式 第一个单词的首字母小 写 其后单词的首字母大写 变量名不应以下划 线或美元符号开头 尽管这在语法上是允许的 变量名应简短且富于描述 变量名的选用应该易 于记忆 即 能够指出其用途 尽量避免单个字 符的变量名 除非是一次性的临时变量 临时变 char c int i float myWidth Java 语言编码规范 第 5 页 量通常被取名为 i j k m 和 n 它们一般用 于整型 c d e 它们一般用于字符型 实例变量 Instance Variables 大小写规则和变量名相似 除了前面需要一个下 划线 int employeeId String name Customer customer 常量 Constants 类常量和 ANSI 常量的声明 应该全部大写 单 词间用下划线隔开 尽量避免 ANSI 常量 容易 引起错误 static final int MIN WIDTH 4 static final int MAX WIDTH 999 static final int GET THE CPU 1 7 7 性能考虑性能考虑 7 1 7 1 使用使用 StringBufferStringBuffer 对象对象 在处理 String 的时候要尽量使用 StringBuffer 类 StringBuffer 类是构成 String 类的基础 String 类将 StringBuffer 类封装了起来 以花费更多时间为代价 为开发人员提供了一个安 全的接口 当我们在构造字符串的时候 我们应该用 StringBuffer 来实现大部分的工作 当 工作完成后将 StringBuffer 对象再转换为需要的 String 对象 比如 如果有一个字符串必须 不断地在其后添加许多字符来完成构造 那么我们应该使用 StringBuffer 对象和她的 append 方法 如果我们用 String 对象代替 StringBuffer 对象的话 会花费许多不必要的创建和释放 对象的 CPU 时间 避免太多的使用 synchronized 关键字避免不必要的使用关键字 synchronized 应该在必 要的时候再使用她 这是一个避免死锁的好方法 7 2 7 2 可移植性可移植性 BorlandJbulider 不喜欢 synchronized 这个关键字 如果你的断点设在这些关键字的作 用域内的话 调试的时候你会发现的断点会到处乱跳 让你不知所措 除非必须 尽量不要 使用 7 3 7 3 换行换行 如果需要换行的话 尽量用 println 来代替在字符串中使用 n 你不要这样 System out print Hello world n 要这样 System out println Hello world 或者你构造一个带换行符的字符串 至少要象这样 String newline System getProperty line separator Java 语言编码规范 第 6 页 System out println Hello world newline 7 4 7 4 PrintStreamPrintStream PrintStream 已经被不赞成 deprecated 使用 用 PrintWrite 来代替她 三 三 Jsp 编码规范编码规范 1 整个 jsp jsp bean 表示层应当尽可能的瘦和简单化 2 牢记大多数的 JSP 都应当是只读的视图 而由页面 bean 来提供模型 3 在尽可能合理的情况下 把业务逻辑从 JSP 中移走 具体于 HTTP 的逻辑 如 对 Cookie 的处理 属于 bean 或支持类中 而不是 JSP 中 4 尽量把条件逻辑放在控制器中而不是放在视图中 5 应当在 JSP 中避免使用页面引入指令 import 指令会促使类的实列化而不是 jsp bean 的实例化 不用 而用 6 jsp 不应该直接去访问请求参数 bean 应当执行这样的处理过程并且输出所处理的模 型数据 7 jsp 不应当访问属性文件 或者使用 JNDI bean 可以访问属性 8 应当避免设计既显示表单又处理结果的页面 9 在 jsp 中避免代码重复 把要重复的功能放在一个包含的 jsp bean 或标记扩展中 使得它能够被重用 10 jsp bean 应当永远不要去产生 HTML 11 在 jsp 中应该避免使用 out pringln 发放来产生页面内容 12 jsp 层不应该直接访问数据 这包括 JDBC 数据库访问和 EJB 访问 13 在长度上 scriptlests 的代码最好不要超过 5 行 14 除了 jsp bean 之外 jsp 不应当去实例化复杂的可读写的对象 如果这样的话 就 有可能在 jsp 中去执行不适当的业务逻辑 15 如果使用了和 并且必须使用简单类型的值来与 外部页面进行通讯的话 就应当使用一个或多个元素 16 应当谨慎地使用标记 在 jsp 中它是一个等价的 goto 17 应当使用隐藏的注释来阻止输出的 HTML 过大 18 在 jsp 中避免进行异常处理 19 每个 jsp 文件中都应当使用一个错误页面来处理不能够从中恢复的异常 20 在 jsp 错误页面中 使用 HTML 注释来显示传递到该页面中的异常跟踪信息 21 只有在能够获得性能上的好处时 才使用 jspInin 方法和 jspDestroy 方法 获取 和放弃资源是 jsp beans 和标记处理器的事 而不是由 jsp 来负责的 22 如果没有充分的理由 就不要在 jsp 中定义方法和内部类 Java 语言编码规范 第 7 页 四 四 Servlet 编码规范编码规范 Servlet 编码规范遵循 java 代码编写规范 为了明确标明此 java 文件是 servlet 程序 规 定所有 Servlet 文件名都以 Servlet 结尾 例如 UploadServlet java 五 五 Jsp 和和 servlet 编程注意事项编程注意事项 在编写 Servlet JSP 程序时 对实例变量一定要小心使用 因为实例变量是非线程安全的 在 Servlet JSP 中 变量可以归为下面的几类 1 类变量 request response session config application 以及 JSP 页面内置的 page pageContext 其中除 了 application 外 其它都是线程安全的 2 实例变量 实例变量是实例所有的 在堆中分配 在 Servlet JSP 容器中 一般仅实例化一个 Servlet JSP 实例 启动多个该实例的线程来处理请求 而