项目指导书(第一学期).doc

目录 项目案例1应用场景1项目基本需求描述1项目运行环境2文档范例4开发文档5项目任务书5项目进展报告（每个阶段提交一份报告）5个人变更记录5用户界面检查表6软件总体设计文档8测试计划11测试报告12Java编码规范131 介绍(Introduction)132 文件名(File Names)133 文件组织(File Organization)144 缩进排版(Indentation)155 注释(Comments)176 声明(Declarations)207 语句(Statements)228 空白(White Space)259 命名规范(Naming Conventions)2610 编程惯例(Programming Practices)2711 代码范例(Code Examples)29项目案例 应用场景 当今社会，网络技术越来越发展，可以说，二十一世纪就是网络的世纪。网络迅猛发展，势不可挡。为了实现资源共享，各式各样的网站发展迅速，各种各样的聊天工具不断更新。某公司希望通过一个聊天工具加强员工和客户之间的沟通和交流。所以制作一个聊天室势在必行。为了实现一个更好的网络交互平台，各用户之间能够实时方便的传递信息，按照用户对系统的要求不同，可以在聊天室里实现公共聊天，也可以邀几个私交好友私聊，同时提供了两个用户之间能够传送文件。本系统是基于方便用户聊天，传递信息，共享资源，所以系统的功能主要是从以上几个模块着手。本项目主要是利用JAVA语言制作一个聊天室,采用的是客户/服务器. 二层的C/S结构是指以单一的服务器和局域网为核心，能通过客户端与用户进行直接对话。主要有二大功能：一是它用于检查用户从键盘等输入的数据,显示应用输出的数据。为使用户能直观地进行操作,一般要使用图形用户接口(GUI),操作简单、易学易用。在变更用户接口时,只需改写显示控制和数据检查程序,而不影响其他。检查的内容也只限于数据的形式和值的范围,不包括有关业务本身的处理逻辑。典型的C/S结构有以下特点：1、服务器负责数据管理及程序处理2、客户机负责界面描述和界面显示3、客户机向服务器提出处理要求4、服务器响应将处理结果返回客户机5、使网络数据流量最少。项目基本需求描述 根据上面的项目背景，拟定以下的一些功能需求。1. 用户注册 2. 用户登录3. 在线用户列表4. 用户公聊5. 用户私聊6. 文件传递扩展功能（如果完整实现一个扩展功能，适当加分）：1 可以切换不同的界面风格2 用户可以更改个人资料，寻找密码3 表情聊天4 IP地址显示n 用户注册第一次用户需要提供个人注册信息，注册的用户名不能重复，密码长度不能少于6位，个人信息必须提供完整，并且存储在数据库中。n 用户登录用户输入用户名和密码，提交给将服务器端的确认，根据从服务器中传过来的确认信息，判断用户登录的情况。如果用户名和密码正确的话，则登录聊天室主界面；如果已经在线，则输出已经在线；否则输出用户名和密码错误，需要重新登录或者注册。n 在线用户列表用户登录之后，需要知道系统中，有哪些用户在线，这样可以方便用户选择与个别用户私聊和传送文件，也可以进行公聊。n 用户公聊用户输入的用户名和密码都正确后，则进入聊天室。聊天主界面主要由四大版块组成：聊天信息、在线用户列表、系统消息和聊天的一些操作。聊天信息版块设计思想：一种就是将客户的聊天信息写入数据库，一种是将其写入向量中。n 用户私聊如果两个人聊的话题比较隐秘，不想被其他人看到，就要使用私聊。在这里，如果说话对象是所有人的话，不能选择私聊；如果从当前用户列表中选择了一个用户之后，则私聊按钮是可选的。n 文件传递两个用户在聊天过程中，可能需要相互间传送文件。象用户聊天信息和在线用户这样一些信息都是保存在服务器端，然后每个客户读取服务器端向量中的内容，此时服务器与客户端的联系是一对多的，而传送文件是一对一的。所以直接传送，不需要经过服务器端保存。项目运行环境 服务器软硬件要求（最低配置）软件：Windows 2000及以上TCP/IP协议硬件：CPU: P及以上 内存：128M硬盘：4G以上客户机软硬件要求软件：Windows 98/ME/2000及以上TCP/IP协议硬件：CPU: P及以上内存：最少128M硬盘：4G以上文档范例 n 文档文档是计算机编程最重要的方面之一。大多数已经完成了程序编写、测试和实现的程序员获得解脱般太过着急地进入下一个项目。另一方面，程序用户抱怨文档老是不完整、不精确或者不正确。仅由程序作者调试程序的情况很少。如果程序没有输入/输出要求、如何执行程序、特定部分的代码做什么之类的详细信息，那么其他用户就很难进行程序调试。因此文档的目的就是要指导用户全面了解程序以及如何正确使用它。文档应在哪个阶段书写呢？大多数情况是在项目结束时才补上的。结果，文档就是些仓促的注解列表，再加上很少的程序运行指导。这个层次所提供的信息不充分，因此项目间的单元测试和检查的想法将有助于制定一份有效和有用的文档。n 程序文档维护计算机程序的主要原因有两个。第一个是由于我们没有能力写出完全没有错误的大型程序所产生的后果；也就是程序bug的定位和改正。错误检测在许多情况下是一个贯彻程序整个生命周期的过程。大多数错误在正式的调试和测试过程中被发现和改正，然后才认为程序完成了。第二个原因是修改现有程序以适应规范的改变。必须修改程序才能满足不断变化的用户需求，才能对程序进行完善。要满足程序文档标准，保留用指定详细信息更新过的每个单元的注释页对程序员而言非常有用，这使得项目文档任务变得非常容易。n 项目文档文档是团队工作的一个重要方面。对于将可重用性作为首要益处的面向对象方法而言更是如此。创建者对一个通用类所作的任何修改应该立即写入文档，这样该类的用户就能注意到。应对文档进行更好的文字处理和适当归档。文档结构应该包括：n 封面页，应具有项目名称、项目小组成员名字及他们的批号和注册号、提交日期、总页数（每页文档都要有页码）。n 问题陈述的简要描述。n 分析和设计，这需要E/R图、类定义和具有有意义字段名的表结构。n 用于测试的样本数据和程序清单。所有这些信息以及新的程序描述和任何有益于程序理解的其它注释都应整理并添加到文档文件中，这样就能对接管该程序或项目且必须重新理解其工作机制的其他人提供帮助。n 参见文档范例开发文档 项目任务书 Java聊天室系统项目的任务进度计划任务名称工作人员工作时间任务描述需求分析开发组2007年7月29日2007年7月31日根据用户提出的需求，制订比较详细的需求分析报告文档系统设计开发组2007年8月1日2007年8月4日项目进展报告（每个阶段提交一份报告） 项目进展报告项目名称Java聊天室系统项目经理报告名称需求分析报告项目所处阶段需求分析阶段时间段2007年7月29日2007年7月31日工作总结经过项目组的详细分析和讨论，确定主要功能需求如下：用户注册 用户登录在线用户列表用户公聊用户私聊文件传递问题与对策1. 问题：文件传送通过点对点还是通过服务器中转。 对策：文件传送通过点对点。 原因：个人变更记录 个人变更记录所属项目变更标题变更内容说明变更内容以及相关技术。执行人日期用户界面检查表 用户界面检查表设计要素重要性检查项适合于检查结果合适性非常重要用户界面是否与软件的功能相融洽？用户界面是否适合于用户的应用环境？解释：如果否定的话，意味着用户不能有效地使用这个软件，是不可原谅的缺陷。这个缺陷是需求分析错误造成的。评审测试容易理解非常重要（1）界面元素有错别字，或者措词含糊、逻辑混乱。（2）消息框的提示文字和按钮在语义上不连贯。（3）确认消息框、告警消息框、通知消息框、过程消息框的风格混淆在一起。解释：如果出现如此低级的缺陷，说明开发人员根本没有把用户界面放在心上，用户很反感这种不敬业的态度。是不可原谅的缺陷。评审测试重要（1） 对于常用的功能，用户能否不必阅读手册就能使用吗？（2） 是否所有界面元素提供了充分而必要的提示？（3） 界面结构和工作流程匹配吗？（4） 提供联机帮助吗？解释：如果实现上述要求，说明界面的细节做得很好。评审测试及时反馈信息重要（1） 是否提供进度条、动画等反映正在进行的比较耗时间的过程？（2） 是否为重要的操作返回必要的结果信息？解释：如果否定的话，说明用户界面不够专业。测试防错处理非常重要（1） 执行破坏性的操作之前，是否获得用户的确认？（2） 输入数据或者递交数据时，是否进行相应的数据校验（检查数据是否合法）（3） 是否根据用户的权限自动隐藏或者禁用某些功能？解释：如果否定的话，说明开发人员没有防错处理的常识，是不可原谅的缺陷。测试可选是否提供Undo功能用以撤销不期望的操作？解释：如果实现该要求，说明界面的细节做得很好。测试一致性重要（1） 同类的界面元素是否有相同的视感和相同的操作方式？（2） 是否符合广大用户使用同类软件的习惯？解释：如果否定的话，说明用户界面不够专业。评审测试个性化可选是否在具备必要的“一致性”的前提下，设计了与众不同的、让用户记忆深刻的界面？解释：如果实现该要求，说明界面很有创意。评审测试合理布局可选（1） 界面的布局符合软件的功能逻辑吗？（2） 界面元素是否在水平或者垂直方向对齐？（3） 界面元素的尺寸是否合理？行、列的间距是否保持一致？（4） 是否恰当地利用窗体和控件的空白，以及分割线条？（5） 窗口切换、移动、改变大小时，界面正常吗？解释：如果否定的话，说明用户界面不够专业。评审测试合理色彩重要（1） 界面的色调是否让人感到和谐、满意？（2） 重要的对象是否用醒目的色彩表示？（3） 色彩使用是否符合行业的习惯？（4） 是否可以让色盲、色弱人员使用？解释：如果实现该要求，说明界面细节很好。评审测试适应用户群体可选（1） 初学者和专家都有合适的方式操作这个界面吗？（2） 色盲或者色弱的用户能正常使用该界面吗？解释：如果实现该要求，说明界面细节很好。测试国际化重要（1） 度量单位、日期格式、人的名字等是否让用户误解？（2） 翻译文字是否地道，是否符合读者习惯？评审测试最少步骤最高效率重要是否用合理的最少步骤实现常用的操作，获得高效率？解释：如果实现该要求，说明界面细节很好。测试可复用重要用户界面的原型、代码、文档是否可以被复用？解释：如果实现该要求，说明软件的需求分析、设计、实现做得很好。开发团队内部评估软件总体设计文档 0. 文档介绍0.1 文档目的与范围编写该文档的目的在于明确java聊天系统的用户需求，使得软件开发人员与用户对待开发软件的需求有统一的、无二义性的认识。该文档所描述的内容，可作为软件确认测试的依据。该文档的读者为用户代表、软件分析人员、开发管理人员和测试人员。0.2 读者对象阅读对象：一般大众0.3 参考文献提示：列出本文档的所有参考文献（可以是非正式出版物），格式如下：标识符 作者，文献名称，出版单位（或归属单位），日期参见java聊天室系统需求说明书0.4 术语与缩写解释缩写、术语解 释1. 系统概述提示：（1）说明本系统“是什么”，（2）描述本系统的主要功能。 java聊天室系统是一个基于客户机/服务器结构的两层的聊天室系统，客户端（前台）包括用户注册，用户登录，多人聊天，私聊，发送附件，传送文件等，采用JAVA编写代码，服务端（后台）进行对客户端信息的各种处理,并使用JDBC访问数据库。2. 设计约束提示：（1）需求约束。体系结构设计人员从需求文档（如用户需求说明书和软件需求规格说明书）中提取需求约束，例如： 本系统应当遵循的标准或规范 软件、硬件环境（包括运行环境和开发环境）的约束 接口/协议的约束 用户界面的约束 软件质量的约束，如正确性、健壮性、可靠性、效率（性能）、易用性、清晰性、安全性、可扩展性、兼容性、可移植性等等。（2）隐含约束。有一些假设或依赖并没有在需求文档中明确指出，但可能会对系统设计产生影响，设计人员应当尽可能地在此处说明。例如对用户教育程度、计算机技能的一些假设或依赖，对支撑本系统的软件硬件的假设或依赖等。3. 开发与运行环境提示：说明本系统应当在什么样的环境下开发和运行，有什么强制要求和建议？类别标准配置最低配置开发环境测试环境运行环境4. 软件的总体设计提示： （1）将系统分解为若干子系统，绘制各种结构图（例如层次结构图、数据流图），说明各子系统的主要功能。（尽可能简单明了，但是能够阐述清楚系统的结构）。（2）说明“如何”以及“为什么”（how and why）如此分解系统。（3）说明各子系统如何协调工作，从而实现原系统的功能。4.1 结构图A在确定本系统的基本结构后，本系统划分的五个子模块的功能如下： 注册模块 提交用户注册信息给服务器，将服务器返回的结果显示给用户； 登录模块 提交用户登录信息给服务器；根据服务器返回的结果决定用户是否可以登录； 聊天实现模块 发送消息，附件，文件等信息给服务器,接收服务端发来的信息进行相应处理。 后台服务模块接收客房端发来的各种信息，进行相应的处理。 数据库模块 响应服务器的指令对数据库进行各种查询或更新操作，将结果返回给服务器。5. 软件体系的面向对象设计5.1用例图5.2 类图类图一: 注册 类图二:登录 类图三:聊天 6. 数据库设计概述6.1 数据库环境说明提示： 说明所采用的数据库系统，设计工具，编程工具，有关配置等6.2 数据库命名规则提示：说明表、字段等命名规则6.3 安全性设计说明提示：考虑用户密码、访问权限等等E/R图6.4 表汇总因为系统只需要一张用户记录表,所以定义了一个数据库User,在库中定义了一张表customer,用来存贮用户信息,以验证用户登录和记录用户注册.l 定义用户信息表(customer)字段数据类型长度能否为空cNamechar10NOT NULLcSexchar30NOT NULLcJobchar20NULLcPasswordchar20NOT NULLvQuestionvarchar20NOT NULLvAnswervarchar30NULLcE_mailchar20NULL7. 用户界面设计概述提示：说明界面设计要素，注意事项，界面原型等。1、注册界面控制条件值预期结果实际结果结论整理按钮“Register”表中没有同一被点击插入表中按钮“ReWrite”None被点击清除内容按钮“GoOut”None被点击退出2、登陆界面控制条件值预期结果实际结果结论整理按钮”Enter”表中存在并且PassWord正确被点击进入聊天室，并且名字显示在标题上按钮”Register”None被点击进入注册界面按钮”ReWrite”None被点击清除所填内容按钮”GoOut”None被点击退出8. 综合考虑8.1 稳定性和可扩展性提示：在“软件”生命周期内，判断哪些需求是不变的，预测哪些需求可能发生的变化。在总体设计的时候，既要使总体结构稳定，又要适应需求变化。8.2 性能分析提示：（1）本系统应当具备哪些性能指标才能满足用户的需求？（2）如何实现性能指标？8.3 复用和移植提示：（1）本系统复用了什么东西（说明出处）？如何解决被复用成果的质量问题？（2）本系统中哪些东西是可以被将来的系统复用的？有什么构思？（3）如何使本系统的功能代码和用户界面代码区分开来8.4 防错与出错处理提示：（1）如何预防系统出错？（2）如果系统出错了，如何处理以减少危害？8.5 其它测试计划 1. 测试范围提示：系统测试小组应当根据项目的特征确定测试类型和主要内容。一般地，系统测试的主要类型包括功能测试、健壮性测试、性能测试、用户界面测试、安全性（security）测试、安装与反安装测试等。测试类型测试内容、描述2. 测试方法提示：例如黑盒测试和白盒测试，解说方法。3. 测试环境与测试辅助工具测试环境测试辅助工具4. 测试完成准则提示：对于非严格系统可以采用“基于测试用例”的准则： （1）功能性测试用例通过率达到100；（2）非功能性测试用例通过率达到95时。对于严格系统，应当补充“基于缺陷密度”的规则：（3）相邻n个CPU小时内“测试期缺陷密度”全部低于某个值m。例如n大于10，m小于等于1。5. 人员与任务表任务描述时间人员6. 问题与对策7. 本计划审批意见提示：如果公司有测试经理的话，本计划需要测试经理的审批。项目经理审批意见：测试经理审批意见：测试报告 测试报告项目名称Java聊天室系统测试任务描述用户注册功能测试人员张三测试时间2007-8-07测试环境和工具Windows XP测试用例或测试内容结果说明用户名长度小于6位（1）无bug（2）发现bug （3）已消除bug未对用户名做长度检查测试总结Java编码规范 1 介绍(Introduction) n 为什么要有编码规范(Why Have Code Conventions)编码规范对于程序员而言尤为重要，有以下几个原因：- 一个软件的生命周期中，80%的花费在于维护- 几乎没有任何一个软件，在其整个生命周期中，均由最初的开发人员来维护- 编码规范可以改善软件的可读性，可以让程序员尽快而彻底地理解新的代码- 如果你将源码作为产品发布，就需要确任它是否被很好的打包并且清晰无误，一如你已构建的其它任何产品 为了执行规范，每个软件开发人员必须一致遵守编码规范。每个人。n 1.2 版权声明(Acknowledgments)本文档反映的是Sun MicroSystems公司，Java语言规范中的编码标准部分。主要贡献者包括：Peter King，Patrick Naughton，Mike DeMoney，Jonni Kanerva，Kathy Walrath以及Scott Hommel。本文档现由Scott Hommel维护，有关评论意见请发至2 文件名(File Names) 这部分列出了常用的文件名及其后缀。n 2.1 文件后缀(File Suffixes)Java程序使用下列文件后缀：文件类别文件后缀Java源文件.javaJava字节码文件.classn 2.2 常用文件名(Common File Names)常用的文件名包括：文件名用途GNUmakefilemakefiles的首选文件名。我们采用gnumake来创建（build）软件。README概述特定目录下所含内容的文件的首选文件名3 文件组织(File Organization) 一个文件由被空行分割而成的段落以及标识每个段落的可选注释共同组成。超过2000行的程序难以阅读，应该尽量避免。“Java源文件范例”提供了一个布局合理的Java程序范例。n 3.1 Java源文件(Java Source Files)每个Java源文件都包含一个单一的公共类或接口。若私有类和接口与一个公共类相关联，可以将它们和公共类放入同一个源文件。公共类必须是这个文件中的第一个类或接口。Java源文件还遵循以下规则：- 开头注释（参见“开头注释”）- 包和引入语句（参见“包和引入语句”）- 类和接口声明（参见“类和接口声明”） 3.1.1 开头注释(Beginning Comments)所有的源文件都应该在开头有一个C语言风格的注释，其中列出类名、版本信息、日期和版权声明： /* * Classname * * Version information * * Date * * Copyright notice */ 3.1.2 包和引入语句(Package and Import Statements)在多数Java源文件中，第一个非注释行是包语句。在它之后可以跟引入语句。例如： package java.awt; import java.awt.peer.CanvasPeer; 3.1.3 类和接口声明(Class and Interface Declarations)下表描述了类和接口声明的各个部分以及它们出现的先后次序。参见“Java源文件范例”中一个包含注释的例子。类/接口声明的各部分注解1类/接口文档注释(/*/)该注释中所需包含的信息，参见“文档注释”2类或接口的声明3类/接口实现的注释(/*/)如果有必要的话该注释应包含任何有关整个类或接口的信息，而这些信息又不适合作为类/接口文档注释。4类的(静态)变量首先是类的公共变量，随后是保护变量，再后是包一级别的变量(没有访问修饰符，access modifier)，最后是私有变量。5实例变量首先是公共级别的，随后是保护级别的，再后是包一级别的(没有访问修饰符)，最后是私有级别的。6构造器7方法这些方法应该按功能，而非作用域或访问权限，分组。例如，一个私有的类方法可以置于两个公有的实例方法之间。其目的是为了更便于阅读和理解代码。4 缩进排版(Indentation) 4个空格常被作为缩进排版的一个单位。缩进的确切解释并未详细指定(空格 vs. 制表符)。一个制表符等于8个空格(而非4个)。n 4.1 行长度(Line Length)尽量避免一行的长度超过80个字符，因为很多终端和工具不能很好处理之。注意：用于文档中的例子应该使用更短的行长，长度一般不超过70个字符。n 4.2 换行(Wrapping Lines)当一个表达式无法容纳在一行内时，可以依据如下一般规则断开之：- 在一个逗号后面断开- 在一个操作符前面断开- 宁可选择较高级别(higher-level)的断开，而非较低级别(lower-level)的断开- 新的一行应该与上一行同一级别表达式的开头处对齐- 如果以上规则导致你的代码混乱或者使你的代码都堆挤在右边，那就代之以缩进8个空格。 以下是断开方法调用的一些例子： someMethod(longExpression1, longExpression2, longExpression3, longExpression4, longExpression5); var = someMethod1(longExpression1, someMethod2(longExpression2, longExpression3); 以下是两个断开算术表达式的例子。前者更好，因为断开处位于括号表达式的外边，这是个较高级别的断开。 longName1 = longName2 * (longName3 + longName4 - longName5) + 4 * longname6; /PREFFER longName1 = longName2 * (longName3 + longName4 - longName5) + 4 * longname6; /AVOID 以下是两个缩进方法声明的例子。前者是常规情形。后者若使用常规的缩进方式将会使第二行和第三行移得很靠右，所以代之以缩进8个空格 /CONVENTIONAL INDENTATION someMethod(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) . /INDENT 8 SPACES TO AVOID VERY DEEP INDENTS private static synchronized horkingLongMethodName(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) . if语句的换行通常使用8个空格的规则，因为常规缩进(4个空格)会使语句体看起来比较费劲。比如： /DONT USE THIS INDENTATION if (condition1 & condition2) | (condition3 & condition4) |!(condition5 & condition6) /BAD WRAPS doSomethingAboutIt(); /MAKE THIS LINE EASY TO MISS /USE THIS INDENTATION INSTEAD if (condition1 & condition2) | (condition3 & condition4) |!(condition5 & condition6) doSomethingAboutIt(); /OR USE THIS if (condition1 & condition2) | (condition3 & condition4) |!(condition5 & condition6) doSomethingAboutIt(); 这里有三种可行的方法用于处理三元运算表达式： alpha = (aLongBooleanExpression) ? beta : gamma; alpha = (aLongBooleanExpression) ? beta : gamma; alpha = (aLongBooleanExpression) ? beta : gamma; 5 注释(Comments) Java程序有两类注释： 实现注释(implementation comments) 文档注释(document comments)实现注释是那些在C+中见过的，使用/*.*/和/界定的注释。文档注释(被称为“doc comments”)是Java独有的，并由/*.*/界定。文档注释可以通过javadoc工具转换成HTML文件。实现注释用以注释代码或者实现细节。文档注释从实现自由(implementation-free)的角度描述代码的规范。它可以被那些手头没有源码的开发人员读懂。注释应被用来给出代码的总括，并提供代码自身没有提供的附加信息。注释应该仅包含与阅读和理解程序有关的信息。例如，相应的包如何被建立或位于哪个目录下之类的信息不应包括在注释中。在注释里，对设计决策中重要的或者不是显而易见的地方进行说明是可以的，但应避免提供代码中己清晰表达出来的重复信息。多余的注释很容易过时。通常应避免那些代码更新就可能过时的注释。注意：频繁的注释有时反映出代码的低质量。当你觉得被迫要加注释的时候，考虑一下重写代码使其更清晰。注释不应写在用星号或其他字符画出来的大框里。注释不应包括诸如制表符和回退符之类的特殊字符。n 5.1 实现注释的格式(Implementation Comment Formats)程序可以有4种实现注释的风格：块(block)、单行(single-line)、尾端(trailing)和行末(end-of-line)。5.1.1 块注释(Block Comments)块注释通常用于提供对文件，方法，数据结构和算法的描述。块注释被置于每个文件的开始处以及每个方法之前。它们也可以被用于其他地方，比如方法内部。在功能和方法内部的块注释应该和它们所描述的代码具有一样的缩进格式。块注释之首应该有一个空行，用于把块注释和代码分割开来，比如： /* * Here is a block comment. */ 块注释可以以/*-开头，这样indent(1)就可以将之识别为一个代码块的开始，而不会重排它。 /*- * Here is a block comment with some very special * formatting that I want indent(1) to ignore. * * one * two * three */ 注意：如果你不使用indent(1)，就不必在代码中使用/*-，或为他人可能对你的代码运行indent(1)作让步。参见“文档注释”5.1.2 单行注释(Single-Line Comments)短注释可以显示在一行内，并与其后的代码具有一样的缩进层级。如果一个注释不能在一行内写完，就该采用块注释(参见“块注释”)。单行注释之前应该有一个空行。以下是一个Java代码中单行注释的例子： if (condition) /* Handle the condition. */ . 5.1.3 尾端注释(Trailing Comments)极短的注释可以与它们所要描述的代码位于同一行，但是应该有足够的空白来分开代码和注释。若有多个短注释出现于大段代码中，它们应该具有相同的缩进。以下是一个Java代码中尾端注释的例子： if (a = 2) return TRUE; /* special case */ else return isPrime(a); /* works only for odd a */ 5.1.4 行末注释(End-Of-Line Comments)注释界定符“/”，可以注释掉整行或者一行中的一部分。它一般不用于连续多行的注释文本；然而，它可以用来注释掉连续多行的代码段。以下是所有三种风格的例子： if (foo 1) / Do a double-flip. . else return false; / Explain why here. /if (bar 1) / / / Do a triple-flip. / . / /else / return false; / n 5.2 文档注释(Documentation Comments)注意：此处描述的注释格式之范例，参见“Java源文件范例”若想了解更多，参见“How to Write Doc Comments for Javadoc”，其中包含了有关文档注释标记的信息(return, param, see)：/javadoc/writingdoccomments/index.html若想了解更多有关文档注释和javadoc的详细资料，参见javadoc的主页：/javadoc/index.html文档注释描述Java的类、接口、构造器，方法，以及字段(field)。每个文档注释都会被置于注释定界符/*.*/之中，一个注释对应一个类、接口或成员。该注释应位于声明之前： /* * The Example class provides . */ public class Example . 注意顶层(top-level)的类和接口是不缩进的，而其成员是缩进的。描述类和接口的文档注释的第一行(/*)不需缩进；随后的文档注释每行都缩进1格(使星号纵向对齐)。成员，包括构造函数在内，其文档注释的第一行缩进4格，随后每行都缩进5格。若你想给出有关类、接口、变量或方法的信息，而这些信息又不适合写在文档中，则可使用实现块注释(见5.1.1)或紧跟在声明后面的单行注释(见5.1.2)。例如，有关一个类实现的细节，应放入紧跟在类声明后面的实现块注释中，而不是放在文档注释中。文档注释不能放在一个方法或构造器的定义块中，因为Java会将位于文档注释之后的第一个声明与其相关联。6 声明(Declarations) n 6.1 每行声明变量的数量(Number Per 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 n 6.2 初始化(Initialization)尽量在声明局部变量的同时初始化。唯一不这么做的理由是变量的初始值依赖于某些先前发生的计算。n 6.3 布局(Placement)只在代码块的开始处声明变量。（一个块是指任何被包含在大括号“”和“”中间的代码。）不要在首次用到该变量时才声明之。这会把注意力不集中的程序员搞糊涂，同时会妨碍代码在该作用域内的可移植性。 void myMethod() int int1 = 0; / beginning of method block if (condition) int int2 = 0; / beginning of if block . 该规则的一个例外是for循环的索引变量 for (int i = 0; i maxLoops; i+) . 避免声明的局部变量覆盖上一级声明的变量。例如，不要在内部代码块中声明相同的变量名： int count; . myMethod() if (condition) int count = 0; / AVOID! . . n 6.4 类和接口的声明(Class and Interface Declarations)当编写类和接口是，应该遵守以下格式规则：- 在方法名与其参数列表之前的左括号“(”间不要有空格- 左大括号“”位于声明语句同行的末尾- 右大括号“”另起一行，与相应的声明语句对齐，除非是一个空语句，“”应紧跟在“”之后 class Sample extends Object int ivar1; int ivar2; Sample(int i, int j) ivar1 = i; ivar2 = j; int emptyMethod() . - 方法与方法之间以空行分隔 7 语句(Statements) n 7.1 简单语句(Simple Statements)每行至多包含一条语句，例如： argv+; / Correct argc-; / Co