江苏亿科达科技发展有限公司
功能块结束：}//end if...userName is null?
循环快结束：}//end for...every user in userList 不要在程序中出现不必要的括号，但有时为了增加可读性和便于理解，当用括号限定相应项。
If，for，while 语句只有单句时，如果该句可能引起阅读混淆，需要用\和\括起来，否则可以省略。
三、注释规范
3.1 基本原则
基本原则：注释应该增加代码的清晰度。代码注释的目的是要使代码更易于被其他开发人员等理解。
注释信息不仅要包括代码的功能，还应给出原因。
除变量定义等较短语句的注释可用行尾注释外，其他注释当避免使用行尾注释。
3.2 文件注释
在每个文件、包的头部都应该包含该文件的功能、作用、作者、版权以及创建、修改记录等。并在其中使用版本仓库标记自动跟踪版本变化及修改记录等信息。注意是标准的C-Style/*...*/ 注释而不是/* ...*/ 形式的JavaDoc 注释，在ECLIPS中使用CODE TEMPLATES会自动添加，如下。
/*
* @(#) Test1.java
* Created Date: Sep 11, 2008 * *
* This software is the confidential and proprietary information of * Jiangsu Ecode Co., Ltd. (\ * disclose such Confidential Information and shall use it only in accordance
* with the terms of the license agreement you entered into with * Jiangsu Ecode Co., Ltd. */
* Copyright (c) Jiangsu Ecode Co., Ltd
6/18
江苏亿科达科技发展有限公司
3.3 Java Doc 注释
对类、方法、变量等的注释需要符合JavaDoc 规范，对每个类、方法都应详细说明其功能、条件、参数等，并使用良好的HTML 标记格式化注释，以使生成的JavaDoc易阅读和理解。
类注释中当包含版本和作者信息，使用版本仓库的标记自动跟踪版本变化和修改记 录，如下。
/**
* 用于示例的类 *
* @author * @version $Rev$
* $Id: Test1.java,v 1.2 2008/09/17 02:25:08 cvsroot Exp $ */
public class Test1 { }
private static final Logger logger = Logger.getLogger(Test1.class); /**
*一个测试的方法
*@param userid 用户编号
*@return 返回用户信息对象，若无该用户信息，则返回null */
private UserInfo getStrings(Integer userid) { }
……………
return userInfo;
3.4 失效代码注释
由/*...*/界定，标准的C-Style 的注释。专用于注释已失效的代码。
/*username = \
password = \ currentCar = \ logined = false;
attributes = new HashMap();
attributes.put(\
失效注释快捷键是Ctrl+Shift+/ ，取消注释是Ctrl+Shift+\\
7/18
江苏亿科达科技发展有限公司
3.5 代码细节注释
由// 界定，专用于注释代码细节，即使有多行注释也仍然使用//，以便与用/**/注 释的失效代码分开除了私有变量外，不推荐使用行末注释。
//设置CarBean
for(int i=0; i < 20; i++) { }
//首先需要生成实例
CarBean bean = new CarBean(); bean.setBaseprice(11); bean.setDescription(\); bean.setName(\); cdao.save(bean);
3.6 注释的格式
? ? ? ? ? ? ?
注释中的第一个句子要以（英文）句号、问号或者感叹号结束。Javadoc 生成工具会将注释中的第一个句子放在方法汇总表和索引中。
为了在JavaDoc 和IDE 中能快速链接跳转到相关联的类与方法，尽量多的使用@see xxx.MyClass，@see xx.MyClass#find(String)。
Class 必须以@author 作者名声明作者，不需要声明手工指定@version 与@date，由版本管理系统保留此信息。
如果注释中有超过一个段落，用
分隔。
示例代码以
包裹。标识(java keyword, class/method/field/argument 名，Constants) 以包裹。 标识在第一次出现时以{@linkxxx.Myclass}注解以便JavaDoc 与IDE 中可以链接。
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