1、1.2 注释规范注释类型用途例子备注文档注释(/*/)1. 类(Class)2. 接口(Interface)3. 成员函数(Member Function)4. 属性(Attribute, Field)的声明前面。/*Customer A customer is any person or organization that we sell services and products to.author S.W. Ambler*/由于Javadoc能文档注释中的某些特定元素,故文档注释通常用于书写项目文档。多行注释(/*/)注释掉暂时不使用的代码。/*This code was comment
2、ed out by J.T. Kirk on Dec 9, 1997 because it was replaced by the preceding code. Delete it after two years if it is still not applicable. . . (the source code )表明这段源代码暂时不使用。可能在以后会改变主意使用它。必须说明原因。单行注释(/)用于成员函数中说明:1. 程序逻辑2. 代码片断3. 临时变量声明等/ Apply a 5% discount to all invoices/ over $1000 as defined by
3、the Sarek/ generosity campaign started in/ Feb. of 1995.建议采用单行注释来进行代码中的说明性行为。1.3 注释的内容名称注释内容Javadoc参数参数Arguments/Parametersl 参数类型l 用途l 使用的约束或者前提条件l 尽量给出一个示例属性Fields/Attributesl 属性描述l 所有可能的取值或取值范围l 示例l 并发中可能存在的问题l 可见性设置。通常属性都设置为“私有”类型,如果设置不一样,请给出原因。l see ClassNamel see ClassName#memberFunctionName成员函
4、数(外部)Member Functionsl 功能、用途以及编写该成员函数的原因l 输入的参数l 返回值l 该函数抛出的“例外”以及抛出的条件l 已知的缺陷l 可见性设置l 代码更改历史l 示例(如何调用该成员函数)l 可能的约束和前提条件l 并发性策略l param name descriptionl return descriptionl exception name descriptionl deprecatedl since成员函数(内部)l 注释局部变量l 注释复杂的代码l 注释控制结构,如分支、循环等,表明其控制流向及意图l 注释代码功能以及缘由局部变量Local Variable
5、s实例变量Instance Variables类Classesl 类的用途l 类实例的所有取值获取值范围l 已知的缺陷(通常在功能尚未完善时)l 类的开发/维护历史l 并发策略l authorl version接口Interfacesl 功能、用途l 什么情况下适用该接口l 什么情况下不适用该接口包Packagesl 文件名l 包名l 版权信息l 所涉及的相关包l 所包含的类l 开发/维护历史2命名2.1 原则l 采用有明确意义的英文单词全名(通常为名词、动词)作为描述符,但不宜于太长(一般不超过20个字符)。l 每一个代码行限制在80个字符以内l 采用常见的专业术语。l 混合大小写形式,便于
6、阅读。通常在定义名称时,采取名称中的每一个单词首字母大写(第一个单词首字母小写),其余字母小写的形式。l 尽量不要采用缩写形式,在其缩写已经被广泛接受的情况下,采用相应的缩写方式,如URL, HTML, XML等。l 虽然Java是大小写敏感的语言,但避免采用只是大小写不同的名称。如lastName和LastName等l 避免使用下划线( _ )以及 $ 符号,特别是前导或后置下划线。因为这些变量经常被用作系统变量。只是在常数定义中,因采用大写形式而加入下划线以增加可读性。2.2 允许的缩写缩写形式messagemsgmanagermgrdatabaseDbcommandCmdimplemen
7、tationimpl2.3 命名规范命名规范Arguments/Parametersl 该参数的英文单词l 第一个英文单词首字母小写l 集合参数采用复数形式firstNamelastNamecustomersFields/Attributesl 该属性的英文单词l 集合属性采用复数形式warpSpeedorderItems布尔形Get函数Boolean Getter Member Functionsl is + 函数名l has +函数名l can +函数名isPersistent()isString()一般Get函数Getter Member Functionsl get + 函数名getF
8、irstName()getLastName()getWarpSpeed()Set函数Setter Member Functionsl set + 函数名setFirstName()setLastName()setWarpSpeed()成员函数l 尽量以一个英文动词开头openFile()addAccount()测试函数l test + 函数名testOpenFile()主要是便于系统测试。在测试完成以后,可以搜索测试函数,将其注释调即可。l 第一个英文单词首字母小写,其余单词首字母大写l 不要采用仅仅是大小写不同的局部变量grandTotalcustomernewAccountl 采用与对象意
9、义相关的l 与普通变量命名法则相同循环计数器Loop countersl 采用惯例i, j, k, counter例外Exceptionse常数Constantsl 所有单词采用大写形式l 单词之间用下划线分隔,以便于阅读MIN_BALANCEDEFAULT_DATEl 所有单词的首字母均大写CustomerSavingsAccountContactablePrompterSingleton为了明确意义,通常最后一个单词有后缀,如“-able”、“-ible”和“-er”等。l 包中各标识符用句点(.)分隔l 由Sun公司发布的标准包是以“java”标识符开头的l 局部包由小写的标识符分隔而成
10、l 全球发行的包由公司域名倒写而成java.awtpersistence.mapping.rationalinterface.screensdao.www.interface.screensdao.www.naisa.dispatcher析构器Destructorsl Java本身没有析构器,但可以激活名为finalize()的函数finalize()组件Components/Widgetsl 组件描述符 + 类型全名l 第一个单词首字母小写okButtoncustomerListfileMenu构建器Constructorsl 名字与类名完全相同Customer()SavingsAccoun
11、t()文件名Filesl 主类名 + “.java”Customer.javaSavingsAccount.java四、格式1源文件基本组织在源文件中,建议采用以下组织。序号内容1包注释FILE: MySourceFile.javaPACKAGE: Copyright (c) 2000 NetDao, Inc. All Rights ReservedCommentsHistory:2000/10/20 : Developer Name Change some code2000/09/12 Developer Name Add Member Function2000/09/01 Developer Name Create this file2包名package ;3引入Java公共包import ;4引入第三方包import com.weblogic.*;5引入自己的项目包6
copyright@ 2008-2022 冰豆网网站版权所有
经营许可证编号:鄂ICP备2022015515号-1