Java开发规范V1.2 - 图文(4)

软件开发项目管理培训

注释结构: /* * @(#){类名称}.java {版本}{创建时间} * {某人或某公司具有完全的版权} * {使用者必须经过许可} * {修改记录：修改人、修改时间、修改内容等} */ 文件注释示例: /* ============================================================ * @(#)User.java 1.2 2011/06/01 * ============================================================ * Copyright (c) 2011 ShengLi Oil Field Victorysoft Co.,Ltd. * (http://www.victorysoft.com.cn) All Right Reserver. * ============================================================ * This software is the confidential and proprietary information of * ShengLi Oil Field Victorysoft Co.,Ltd.(\* You shall not disclose such Confidential Information and shall user * it only in accordance with terms of the license agreement * you entered into with VictorySoft. * ============================================================ * 修改人: vseaf * 修改时间: 2011/06/15 * 修改内容: …… * ============================================================ 3.4 类、接口注释

在类、接口定义之前当对其进行注释，包括类、接口的目的、作用、功能、

7

软件开发项目管理培训

继承于何种父类，实现的接口、实现的算法、使用方法、示例程序等。 类注释示例 : /** *

字符串实用类。

（类描述） * * 定义字符串操作时所需要用到的方法，如转换中文、HTML标记处理等。 * * @author: vseaf（作者） * @version: 1.2 （版本） */ public class StringUtil { ? } 3.5 方法注释

依据标准JavaDoc规范对方法进行注释，以明确该方法功能、作用、各参数含义以及返回值等。复杂的算法用/**/在方法内注解出。 参数注释时当注明其取值范围等

返回值当注释出失败、错误、异常时的返回情况。

异常当注释出什么情况、什么时候、什么条件下会引发什么样的异常 。 方法注释示例 ; /** * 执行查询。 * * 该方法调用Statement的executeQuery(sql)方法并返回ResultSet *结果集。 * 8

软件开发项目管理培训

* @param sql 标准的SQL语句 * @return ResultSet结果集，若查询失败则返回null * @throws SQLException 当查询数据库时可能引发此异常 */ public ResultSet executeQuery(String sql) throws SQLException { //Statement和SQL语句都不能为空 if(null != stmt && !StringUtil.isEmpty(sql)){ //返回查询执行结果 return stmt.executeQuery(sql); } return null; }//end executeQuery() 3.6 其他注释

应对重要的变量加以注释，以说明其含义等。

应对不易理解的分支条件表达式加注释。不易理解的循环，应说明出口条件。过长的方法实现，应将其语句按实现的功能分段加以概括性说明。

对于异常处理当注明正常情况及异常情况或者条件，并说明当异常发生时程序当如何处理。

3.7 注释参考表

注释参考表 ：

项目 注释内容 参数类型 参数 参数用来做什么 约束或前提条件 示例 9

软件开发项目管理培训

字段描述 注释所有使用的不变量 字段/属性 示例 并行事件 可见性决策 类的目的 已知的问题 类 类的开发/维护历史、版本 注释出采用的不变量 并行策略 文件名/标识信息 版权信息 编译单元 （文件） 许可信息 创建/修改记录 获取成员方法 若可能，说明为什么使用滞后初始化 目的 接口 它应如何被使用以及如何不被使用 局部变量 用处/目的 成员方法做什么以及它为什么做这个 哪些参数必须传递给一个成员方法 成员方法返回什么 已知的问题 任何由某个成员方法抛出的异常 成员方法注释 可见性决策 成员方法是如何改变对象的 包含任何修改代码的历史 如何在适当情况下调用成员方法的例子 适用的前提条件和后置条件 控制结构 代码做了些什么以及为什么这样做 成员方法内部注释 局部变量 难或复杂的代码 处理顺序 包 包的功能和用途

10

软件开发项目管理培训

第4章 命名 4.1 基本原则

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

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

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

? 采用大小写混合，提高名字的可读性。一般应该采用小写字母，但是类和接口的名字的首字母，以及任何中间单词的首字母应该大写。包名全部小写。

如：com.sun.usertest，其中usertest应全部小写，不应这样：userTest ? 尽量少用缩写，但如果一定要使用，当使用公共缩写和习惯缩写等，如实现（implement）可缩写成impl，经理（manager）可缩写成mgr等，具体参看附录之《常用缩写简表》，严禁滥用缩写。

? 不影响理解名称含义的情况下，尽量避免使用长名字（最好不超过 25 个字母），对于较长单词建议使用缩写，并加注释说明。 ? 避免使用相似或者仅在大小写上有区别的名字。

?

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

11

…… 此处隐藏：1141字，全部文档内容请下载后查看。喜欢就下载吧 ……