JAVA开发编码规范1.2(3)

3.7 注释的内容

? ? ? ? ? ?

8/18

对于API 函数如果存在契约，必须写明它的前置条件(precondition)，后置条件(postcondition)，及不变式(invariant)。

对于调用复杂的API 尽量提供代码示例。

对于已知的Bug 需要声明。

在本函数中抛出的unchecked exception 尽量用@throws 说明。

注释中的每一个单词都要有其不可缺少的意义，注释里不写\name -名字\无意义的内容。

注释的标签必须有内容，不能存在空的@param name，空的@return。

江苏亿科达科技发展有限公司

3.8 Null 规约

如果方法允许Null 作为参数，或者允许返回值为Null，必须在JavaDoc 中说明。

如果没有说明，方法的调用者不允许使用Null 作为参数，并认为返回值是Null Safe的。

/**

*

* @param actionEvent 买车按钮的动作事件 * @throws Exception 一般异常 */

public void buyCar(ActionEvent actionEvent) throws Exception { }

9/18

江苏亿科达科技发展有限公司

4 命名规范(Naming Conventions)

规范的命名能使程序更易阅读，从而更易于理解。它们也可以提供一些标识功能方面的信息，有助于更好的理解代码和应用。

4.1 基本约定

?

使用可以准确说明变量/字段/类/接口/包等的完整的英文描述符。例如，采用类似firstName，listAllUsers 或CorporateCustomer 这样的名字，严禁使用汉语拼音及不相关单词命名，虽然Java 支持Unicode 命名，但本规范规定对包、类、接口、方法、变量、字段等不得使用汉字等进行命名。

采用该领域的术语。如果用户称他们的“客户”(clients) 为“顾客”(customers)，那么就采用术语Customer 来命名这个类，而不用Client。

采用大小写混合，提高名字的可读性。一般应该采用小写字母，但是类和接口的名字的首字母，以及任何中间单词的首字母应该大写。包名全部小写。 尽量少用缩写，但如果一定要使用，当使用公共缩写和习惯缩写等，如实现（implement）可缩写成impl，应用程序（application）可缩写成app 等，严禁滥用缩写。 ? ? ? ?

? ? ?

避免使用长名字（最好不超过25 个字母）。 避免使用相似或者仅在大小写上有区别的名字。

避免使用数字，但可用2 代替to，用4 代替for 等，如：go2Jsp。

遇到缩写如XML 时， 仅首字母大写， 即loadXmlDocument() 而不是loadXMLDocument()。

4.2 文件、包

? ? ? ? ?

文件名当与其类严格相同，所有单词首字母大写。

包名一般以项目或模块名命名，少用缩写和长名，一律小写。 基本包：com.candur，所有包、文件都从属于此包。

包名按规则组成：[基本包] . [项目名] . [模块名] . [子模块名]... 不得将类直接定义在基本包下，所有项目中的类、接口等都当定义在各自的项目和模块包中。

4.3 类、接口

所有单词首字母大写。使用能确切反应该类、接口含义、功能等的词。一般采用名词。接口可以可以在名词前加大写I，如IBookDao,，BookDaoIF。

10/18