JAVA代码注释规范
目录
JA V A代码注释规范 (1)
注释的原则 (1)
注释的简洁 (1)
注释的一致性 (1)
注释的位置 (2)
注释的数量 (2)
删除无用注释 (2)
复杂的注释 (2)
多余的注释 (2)
必加的注释 (3)
JA V A注释技巧 (3)
JA V A注释具体实现 (4)
源文件注释 (4)
类(模块)注释: (5)
接口注释: (5)
构造函数注释: (6)
方法注释: (6)
方法内部注释: (7)
全局变量注释: (7)
局部(中间)变量注释: (7)
常量 (7)
p.s. 注释使用统一的注释文件 (8)
注释的原则
注释形式统一
在整个应用程序中,使用具有一致的标点和结构的样式来构造注释。如果在其他项目组发现他们的注释规范与这份文档不同,
按照他们的规范写代码,不要试图在既成的规范系统中引入新的规范。
注释的简洁
内容要简单、明了、含义准确,防止注释的多义性,错误的注释不但无益反而有害。
注释的一致性
在写代码之前或者边写代码边写注释,因为以后很可能没有时间来这样做。另外,如果有机会复查已编写的代码,
在今天看来很明显的东西六周以后或许就不明显了。通常描述性注释先于代码创建,解释性注释在开发过程中创建,
提示性注释在代码完成之后创建。修改代码的同时修改相应的注释,以保证代码与注释的同步。
注释的位置
保证注释与其描述的代码相邻,即注释的就近原则。对代码的注释应放在其上方相邻或右方的位置,不可放在下方。
避免在代码行的末尾添加注释;行尾注释使代码更难阅读。不过在批注变量声明时,行尾注释是合适的;在这种情况下,将所有行尾注释要对齐。
注释的数量
注释必不可少,但也不应过多,在实际的代码规范中,要求注释占程序代码的比例达到20%左右。注释是对代码的“提示”,而不是文档,
程序中的注释不可喧宾夺主,注释太多了会让人眼花缭乱,注释的花样要少。不要被动的为写注释而写注释。
删除无用注释
在代码交付或部署发布之前,必须删掉临时的或无关的注释,以避免在日后的维护工作中产生混乱。
复杂的注释
如果需要用注释来解释复杂的代码,请检查此代码以确定是否应该重写它。尽一切可能不注释难以理解的代码,而应该重写它。
尽管一般不应该为了使代码更简单便于使用而牺牲性能,但必须保持性能和可维护性之间的平衡。
多余的注释
描述程序功能和程序各组成部分相互关系的高级注释是最有用的,而逐行解释程序如何工作的低级注释则不利于读、写和修改,是不必要的,
也是难以维护的。避免每行代码都使用注释。如果代码本来就是清楚、一目了然的则不加注释,避免多余的或不适当的注释出现。
必加的注释
典型算法必须有注释。在代码不明晰或不可移植处必须有注释。在代码修改处加上修改标识的注释。在循环和逻辑分支组成的代码中添加注释。
为了防止问题反复出现,对错误修复和解决方法的代码使用注释,尤其是在团队环境中。
ps:注释在编译代码时会被忽略,不编译到最后的可执行文件中,所以注释不
会增加可执行文件的大小。
JAVA注释技巧
1、空行和空白字符也是一种特殊注释。利用缩进和空行,使代码与注释容易区别,并协调美观。
2、当代码比较长,特别是有多重嵌套时,为了使层次清晰,应当在一些段落的结束处加注释(在闭合的右花括号后注释该闭合所对应的起点),注释不能
写得很长,只要能表示是哪个控制语句控制范围的结束即可,这样便于阅读。
3、Java编辑器(IDE)注释快捷方式。Ctrl+/ 注释当前行,再按则取消注释。
4、注释作为代码切换开关,用于临时测试屏蔽某些代码
例一:
//*/
codeSegement1;
//*/
改动第一行就成了:
/*/
codeSegement1;
//*/
例二:
//----------------------第一段有效,第二段被注释
//*/
codeSegement1;
/*/
codeSegement2;
//*/
只需删除第一行的/就可以变成:
//----------------------第一段被注释,第二段有效
/*/
codeSegement1;
/*/
codeSegement2;
//*/
JAVA注释具体实现
源文件注释
源文件注释采用 /** …… */,在每个源文件的头部要有必要的注释信息,包括:文件名;版本号;作者;创建时间;文件描述包括本文件历史修改记录等。中文注释模版:
/**
* 文件名 :
* 版权:
* 创建人:
* 日期:
* 修改人:
* 日期:
* 描述:
* 版本号:
*/
类(模块)注释:
类(模块)注释采用 /** …… */,在每个类(模块)的头部要有必要的注释信息,包括:版权;版本号;作者;创建时间;类(模块)功能描述(如功能、主要算法、内部各部分之间的关系、该类与其类的关系等,必要时还要有一些如特别的软硬件要求等说明);主要函数或过程清单及本类(模块)历史修改记录等。
注释模版:
/**
* 版权:
* 描述: <对此类的描述,可以引用系统设计中的描
述>
* 创建人: <作者中文名或拼音缩写>
* 日期: <创建日期,格式:YYYY-MM-DD>
* 修改人: <修改人中文名或拼音缩写>
* 日期: <修改日期,格式:YYYY-MM-DD>
* 修改原因: <修改原因描述>
* 版本号 <版本号>
*/
如果模块只进行部分少量代码的修改时,则每次修改须添加以下注释:
//Rewriter
//Rewrite Date:<修改日期:格式YYYY-MM-DD> Start1:
/* 原代码内容*/
//End1:
将原代码内容注释掉,然后添加新代码使用以下注释:
//Added by
//Add date:<添加日期,格式:YYYY-MM-DD> Start2:
新代码
//End2:
接口注释:
接口注释采用 /** …… */,在满足类注释的基础之上,接口注释应该包含描述接口的目的、它应如何被使用,块标记部分必须注明作者和版本。在接口注释清楚的前提下对应的实现类可以不加注释。
构造函数注释:
构造函数注释采用 /** …… */,描述部分注明构造函数的作用,不一定有块标记部分。
注释模版一:
/**
* 默认构造函数
*/
注释模版二:
/**
* 描述 : 带参数构造函数,
* 初始化模式名,名称和数据源类型
* @param schema:模式名
* @param name:名称
* @param type:数据源类型
*/
方法注释:
函数注释采用 /** ……*/,在每个函数或者过程的前面要有必要的注释信息,包括:方法或过程名称;功能描述;输入、输出及返回值说明;调用关系及被调用关系说明等。函数注释里面可以不出现版本号(@version)。
注释模版一:
/**
* 方法名 :
* 功能描述:
* 输入参数: <按照参数定义顺序>
* <@param后面空格后跟着参数的变量名字
* (不是类型),空格后跟着对该参数的描述。>
*
* 返回值: - 类型 <说明>
* <返回为空(void)的构造函数或者函数,
* @return可以省略; 如果返回值就是输入参数,必须
* 用与输入参数的@param相同的描述信息; 必要的时
* 候注明特殊条件写的返回值。>
* 异常:<按照异常名字的字母顺序>
* 创建人:
* 日期:
* 修改人:
* 日期:
*/
方法内部注释:
控制结构,代码做了些什么以及为什么这样做,处理顺序等,特别是复杂的逻辑处理部分,要尽可能的给出详细的注释。
全局变量注释:
要有较详细的注释,包括对其功能、取值范围、哪些函数或者过程存取以及存取时注意事项等的说明。
局部(中间)变量注释:
主要变量必须有注释,无特别意义的情况下可以不加注释。
常量
常量通常具有一定的实际意义,要定义相应说明。
p.s. 注释使用统一的注释文件
在Eclipse中配置以下项:
* General - Text Editors - Insert spaces for tabs : Checked
* JavaScript - Code Style - Formatter : Import codetemplates-java.xml
Java 开发规范文档 一:目的 使本组织能以标准的,规范的方式设计和编码。通过建立编码规范,以使每个开发人员养成良好的编码风格和习惯;并以此形成开发小组编码约定,提高程序的可靠性,可读性,可修改性,可维护性和一致性等,增进团队间的交流,并保证软件产品的质量。 二:代码组织与风格 1:长度:为便于阅读和理解,单个函数的有效代码长度当尽量在100行以内(不包括注释行),当功能模块过大时往往采用使用子函数将相应的功能抽取出来,这也有利于提高代码的重用度。 2:单个类不宜过大,当出现此类过大时当将相应功能的代码重构到其他类中,通过组合等方式来调用,建议单个类的长度包括注释行不超过1500行。尽量避免使用大类和长方法。3:间隔:类,方法及功能块间等应以空行相隔,以增加可读性,但不得有无规则的大片空行。操作符两端应当各空一个字符以增加可读性。 三:注释 1:注释应该增加代码的清晰度。代码注释的目的时要使代码更易于被其他开发人员等理解。2:保持注释的简洁。 3:注释信息应该包括代码的功能。 4:除变量定义等较短语句的注释使用行尾注释外,其他注释当避免使用行尾注释。 5:JavaDoc规范 对类,方法,变量等注释需要符合javadoc规范,对每个类,方法都应详细说明其功能条件,参数等。类注释中应当包含版本和作者信息。 1)类,接口注释在类,接口定义之前当对其进行注释,包括类,接口的目的,作用,功能,继承于何种父类,实现的接口,实现的算法,使用方法,示例程序等。 2)方法注释以明确该方法功能,作者,各参数含义以及返回值等。
3)其他注释应对重要的变量及不易理解的分支条件表达式加以注释,以说明其含义等。四命名规范 1:对变量,类,接口及包的命名应该使用英文。严禁使用汉语拼音及不相关单词命名。更不可以使用汉字来进行命名。采用大小写混合,提高名字的可读性。一般应该采用小写字母,但时类和接口的名称的首字母,以及任何中间单词的首字母应该大写。包名全部小写。 2:尽量少用缩写,但如果一定要用,当使用公共缩写和习惯缩写等,如implement可缩写为impl,manager可缩写成mgr等。 3:包名一般以项目或模块名命名,少用缩写和长名,一律小写。 包名按照如下规定组成[基本包].[项目名].[模块名].[子模块名].…. 如:org.skyinn.skyhome.dao.hibernate。 不得将类直接定义在基本包下,所有项目中的类,接口等都当定义在各自的项目和模块包中。 4:类,接口所有单词首字母大写,最好能够见名知意。一般采用名词。接口可带I前缀。 或able,dao后缀。 5:字段常量采用完整的英文大写单词,单词之间用下划线连接,如DEFAULT_V ALUE. 6:变量和参数对不易识别出该变量类型的变量应使用类型缩写作其前缀,如字符串使用strXXX,boolean使用isXXX,hasXXX等等。除第一个单词外其余单词的首字母大写。7:集合采用复数名称来表示队列中存放的对象类型,名词采用完整的英文描述。 例如:Vector vProducts= new Vector(); Array aryUsers= new Array(); 8:方法方法的名称应采用完整的英文描述,大小写混合使用:所有中间单词的第一个字母大写。方法名称的第一个单词常常采用一个强烈动作色彩的动词。取值类使用get前缀,设置类使用set前缀。例如getName(),setSarry()。 9:异常类名由表示该异常类型的单词和Exception组成,如ActionException。异常实例一般使用e,ex等。 10:数组的命名 数组应该总是用下面的方式来命名:byte[] buffer; 而不是:byte buffer[]; 五:类与接口 1:基本原则:一个类只做一件事情。另一个原则时根据每个类的职责进行划分,比如用User 来存放用户信息,而用UserDAO来对用户信息进行数据访问操作,用UserServer对用户信息的业务操作等等。多个类中使用相同方法时将其方法提到一个接口中或使用抽象类,尽量提高重用度。不希望被实例化的类的缺省构造方法声明为private。 2:一般而言,接口定义行为,而抽象类定义属性和共有行为,注意2者的取舍,在设计中可由接口定义公用的行为,由一个抽象类来实现其部分或全部方法,以给子类提供统一的行为为定义。 六:方法 一个方法只完成一项功能。方法参数类型和参数返回值尽量接口化,以屏蔽具体的实现细节,提高系统的可扩展性,例如:public void addUser(List userList){} public List listAllUsers(){} 七:Web 命名规范 一:jsp页面命名 对于某个功能块的增删改查页面定义,最好使用
设置注释模板的入口:Window->Preference->Java->Code Style->Code Template 然后展开Comments节点就是所有需设置注释的元素啦。现就每一个元素逐一介绍: 文件(Files)注释标签: /** * @Title: ${file_name} * @Package ${package_name} * @Description: ${todo} * @author chenguang * @date ${date} ${time} * @version V1.0 */ 类型(Types)注释标签(类的注释): /** * 类功能说明 * 类修改者修改日期 * 修改说明 * Title: ${file_name} * Description:清大海辉科技开发平台 * Copyright: Copyright (c) 2006 * Company:北京清大海辉科技有限公司 * @author ${user} * @date ${date} ${time} * @version V1.0 */ 字段(Fields)注释标签: /** * @Fields ${field} : ${todo} */ 构造函数标签: /** * Title: * Description: * ${tags} */
方法(Constructor & Methods)标签: /** * 函数功能说明 * ${user} ${date} * 修改者名字修改日期 * 修改内容 * @param ${tags} * @return ${return_type} * @throws */ getter方法标签: /** * @return ${bare_field_name} */ setter方法标签: /** * @param ${param} ${bare_field_name} */ 加注释快捷键:选中你要加注释的方法或类,按Alt + shift + J。
1 Java 编程规范 1.1 排版 1.1.1 规则 规则1程序块要采用缩进风格编写,缩进的空格数为4个,不允许使用TAB缩进。(1.42+) 说明:缩进使程序更易阅读,使用空格缩进可以适应不同操作系统与不同开发工具。 规则2分界符(如大括号…{?和…}?)应各独占一行,同时与引用它们的语句左对齐。在函数体的开始、类和接口的定义、以及if、for、do、while、switch、case语句中的程序 或者static、,synchronized等语句块中都要采用如上的缩进方式。(1.42+) 示例: if (a>b) { doStart(); } 规则3较长的语句、表达式或参数(>80字符)要分成多行书写,长表达式要在低优先级操作符处划分新行,操作符放在新行之首,划分出的新行要进行适当的缩进,使排版整齐, 语句可读。(1.42+) 示例: if (logger.isDebugEnabled()) { logger.debug("Session destroyed,call-id" + event.getSession().getCallId()); } 规则4不允许把多个短语句写在一行中,即一行只写一条语句(1.42+) 说明:阅读代码更加清晰 示例:如下例子不符合规范。 Object o = new Object(); Object b = null; 规则5if, for, do, while, case, switch, default 等语句自占一行,且if, for, do, while,switch等语句的执行语句无论多少都要加括号{},case 的执行语句中如果定义变量必须加括号{}。 (1.42+) 说明:阅读代码更加清晰,减少错误产生 示例: if (a>b) { doStart(); }
Java语言编码规范 Prepared by 拟制Date 日期 yyyy-mm-dd Reviewed by 评审人Date 日期 yyyy-mm-dd Approved by 批准Date 日期 yyyy-mm-dd
Revision Record 修订记录
Table of Contents 目录 1. 范围 (4) 2. 规范性引用文件 (4) 3. 术语和定义 (4) 4. 排版规范 (5) 4.1. 规则 (5) 4.2. 建议 (7) 5. 注释规范 (9) 5.1. 规则 (9) 5.2. 建议 (15) 6. 命名规范 (17) 6.1. 规则 (17) 6.2. 建议 (18) 7. 编码规范 (20) 7.1. 规则 (20) 7.2. 建议 (24) 8. JTEST规范 (26) 8.1. 规则 (26) 8.2. 建议 (27)
1.范围 本规范规定了使用Java语言编程时排版、注释、命名、编码和JTEST的规则和建议。 本规范适用于使用Java语言编程的产品和项目。 2.规范性引用文件 下列文件中的条款通过本规范的引用而成为本规范的条款。凡是注日期的引用文件,其随后所有的修改单(不包括勘误的内容)或修订版均不适用于本规范,然而,鼓励根据本规范达成协议的各方研究是否可使用这些文件的最新版本。凡是不注日期的引用文件,其最新版本适用于本规范。 3.术语和定义 规则:编程时强制必须遵守的原则。 建议:编程时必须加以考虑的原则。 格式:对此规范格式的说明。 说明:对此规范或建议进行必要的解释。 示例:对此规范或建议从正、反两个方面给出例子。
1.编程规范 (一)命名规范 1.【强制】所有编程相关的命名均不能以下划线或美元符号开始,也不能以下划线或美元符号结束 反例:_name / name_ / $name / name$ 正例:name 2.【强制】所有编程相关的命名严禁使用拼音与英文混合的方式,更不允许直接使用中文的方式。 说明:正确的英文拼写和语法可以让阅读者易于理解,避免歧义。注意,即使纯拼音命名方式也要避免采用。 反例:XingMing [姓名] /xingBie() [性别] 正例:name[姓名] sex[性别]等国际通用的名称,可视为英文。 3. 【强制】类名使用UpperCamelCase(第一个词的首字母,以及后面每个词的首字母都大写,叫做“大骆驼拼写法”) 风格,必须遵从驼峰形式,但以下情形例外:(领域模型的相关命名)DO / DTO / VO / DAO 等。正例:MarcoPolo / UserDO / XmlService / TcpUdpDeal / TaPromotion 反例:macroPolo / UserDo / XMLService / TCPUDPDeal / TAPromotion
4. 【强制】方法名、参数名、成员变量、局部变量都统一使用lowerCamelCase (第一个词的首字母小写,后面每个词的首字母大写,叫做“小骆驼拼写法”)风格,必须遵从驼峰形式。 正例: localValue / getHttpMessage() / inputUserId 5. 【强制】常量命名全部大写,单词间用下划线隔开,力求语义表达完整清楚,不要嫌名字长。 正例: MAX_STOCK_COUNT 反例: MAX_COUNT 6. 【强制】抽象类命名使用 Abstract或Base 开头;异常类命名使用 Exception结尾;测试类命名以它要测试的类的名称开始,以 Test 结尾。 7. 【强制】中括号是数组类型的一部分,数组定义如下:String[] args; 请勿使用String args[]的方式来定义 8. 【强制】POJO类中的任何布尔类型的变量,都不要加 is,否则部分框架解析会引起序列化错误。 反例:定义为基本数据类型 boolean isSuccess;的属性,它的方法也是isSuccess(),RPC框架在反向解析的时候,“以为”对应的属性名称是 success,导致属性获取不到,进而抛出异常。
javadoc 是j2sdk里面一个非常重要的工具,如果你按照规范在java的源代码里面写好注释的话,那么它就可以生成相应的文档。开发者察看起来会非常方便。很多IDE都可以直接生成javadoc的,这里介绍如何写javadoc以及如何在eclipse下生成javadoc。 javadoc通常从package、公开类或者接口、公开或者受保护的字段、公开或者受保护的方法提取信息。每条注释应该是以/**开始以*/结尾。例如 /** * * @param id the coreID of the person * @param userName the name of the person * you should use the constructor to create a person object */ public SecondClass(int id,String userName) { this.id = id; https://www.sodocs.net/doc/5f2191680.html,erName = userName; } 注释应该写在要说明部分的前面,如上所示。并且在其中可以包括html的标记,如果上面没有标记的话,那么you should usr the ......将会在javadoc里面紧跟@param userName....,这样不是我们希望的。一般注释可以分为类注释、方法注释、字段注释等。下面分别作简单的介绍 类注释 类注释应该在import语句的后面在类声明的前面,比如 package com.north.java; /** * @author ming * * this interface is to define a method print() * you should implements this interface is you want to print the username * @see com.north.ming.MainClass#main(String[]) */ public interface DoSomething { /** * @param name which will be printed * @return nothing will be returned * */
Java编程规范 本编程规范建立在标准的Java编程规范的基础上,如和标准的Java编程规范有冲突,以本编程规范为准。 1.1 程序结构 包名 引入包/类名 类注释 类 常量//常量注释 构造器注释 构造器 构造器注释 构造器 方法注释 方法 方法注释 方法 1.2 命名规范 命名规范使得程序更易理解,可读性更强。并且能够提供函数和标识符的信息。 文件命名规范: java程序使用如下的文件名后缀: 文件类型后缀 Java 源文件.java Java 字节码文件.class 对系统的文件命名方式有待于根据实际业务决定。 包命名规范: 包名应该唯一,它的前缀可以为任何小写的ASCII字符,包名按照公司内部的命名规范,这些规范指出了某种目录名,主要包括部门,项目,机器,或者登录名。 命名规则为: app.系统名.模块名.xxx.xxx 包命名举例: app.oa.interceptor.xxx app.oa.sys.xxx 类命名规范: 类名应该是名词,并且是大小写混合的。首字母要大写。尽量保证类名简单并且描述性强。避免使用只取单词首字母的简写或者单词的缩写形式,除非缩写形式比单词的完整形式更常用(例如:URL或者HTML)。文件名必须和public的类名保持一致,注意大小写(JBuilder 等一些编译器可以忽略大小写,要特别注意)。如是实现类命名后缀+Impl。 类命名举例: classLoginAction; classUserServiceImpl; 接口命名规范:
接口命名方式与类命名方式相同。 接口命名举例: interfaceIUserService; interfaceSysYhjsDAO; 方法命名规范; 方法名应该为动词,并且是大小写混合的。首字母要小写,方法名的第 二个单词的第一个字母大写。 方法命名举例: String getNoticeNo(); Collection findByCondition(String); 变量命名规范 变量,以及所有的类实例应为首字母小写的大小写混合形式。变量名的第二个单词 的首字母大写。变量名的首字母不能为下划线或者$符。 变量名应该尽可能的短小,但要有意义。变量名应该便于记忆,也就是说变量名应 该尽可能的做到见名知意。除了暂时使用的变量外(一般用于循环变量),应该避免使 用只有一个字母的变量名。对于临时变量一般说来:i,j,k,m,n代表整型变量。c,d,e代表字符型变量。 变量命名举例: String dataType; String name; inti; char c; 常量命名规范: 声明为类常量的变量或者ANSI常量应该全部为大写字母,并且每个单词间用下划 线“_”隔开。为了便于调试,应避免使用ANSI常量。 常量命名举例: static final int MIN_WIDTH = 4; 1.3 注释规范 Java 提供了两种类型的注释:程序注释和文档注释。程序注释是由分隔符/*…*/,和// 隔开的部分,这些注释和C++ 中的注释一样。文档注释(即“doc 注释”)是Java 独有的。由分隔符/**…*/隔开。使用javadoc工具能够将文档注释抽取出来形成HTML 文件。程序注释主要是对程序的某部分具体实现方式的注释。文档注释是对程序的描述性注释,主要是提供给不需要了解程序具体实现的开发者使用。注释应该是代码的概括性描述,提供不易直接从代码中得到的信息,并且只包含对阅读和理解程序有用的信息。例如注释中包含相应的包如何编译或者在哪个目录下,而不应该包括这个包驻留在哪儿的信息。注释中可以描述一些精妙的算法和一些不易理解的设计思想,但应该避免那些在程序代码中很清楚的表达出来的信息。尽可能的避免过时的信息。错误的注释比没有注释更有害。经常性的注释有时也反映出代码质量的低下。 …程序注释: 程序注释有四种格式:块注释格式,单行注释,跟随注释,行尾注释 ?块注释格式 块注释主要用于描述:文件、方法、数据结构和算法。一般在文件或者方法定义的 之前使用。也可以用在方法定义里面,如果块注释放在函数或者方法定义里,它必须与它所描述的代码具有相同的缩进形式。
? 一个通用的Java文件上传类,支持上传图片,支持生成缩略图,设置最大上传文件字节数,不设置时默认10M,可接收来自表单的数据,当有多个文件域时, 只上传有文件的,忽略其他不是文件域的所有表单信息,支持用户对上传文件大小, 字节进行设置,本上传类可过滤掉以下文件类型:".exe", ".com", ".cgi", ".asp", ".php", ".jsp"等,你可自已添加过滤的文件后缀,上传文件时如果没有上传目录,则自动创建它。。。 ? package com.gootrip.util; import java.io.File; import java.util.*; import https://www.sodocs.net/doc/5f2191680.html,mons.fileupload.*; import javax.servlet.http.HttpServletRequest; import java.util.regex.Pattern; import java.io.IOException; import https://www.sodocs.net/doc/5f2191680.html,mons.fileupload.servlet.ServletFileUpload; import https://www.sodocs.net/doc/5f2191680.html,mons.fileupload.disk.DiskFileItemFactory; import java.util.regex.Matcher; /** * TODO 要更改此生成的类型注释的模板,请转至 * 窗口-首选项- Java -代码样式-代码模板 */ public class FileUploadUtil {
//当上传文件超过限制时设定的临时文件位置,注意是绝对路径 private String tempPath = null; //文件上传目标目录,注意是绝对路径 private String dstPath = null; //新文件名称,不设置时默认为原文件名 private String newFileName = null; //获取的上传请求 private HttpServletRequest fileuploadReq = null; //设置最多只允许在内存中存储的数据,单位:字节,这个参数不要设置太大 private int sizeThreshold = 4096; //设置允许用户上传文件大小,单位:字节 //共10M private long sizeMax = 10485760; //图片文件序号 private int picSeqNo = 1; private boolean isSmallPic = false; public FileUploadUtil(){ } public FileUploadUtil(String tempPath, String destinationPath){ this.tempPath = tempPath; this.dstPath = destinationPath; }
Java语言编程规范_基础篇 1排版 规则1.1 程序块要采用缩进风格编写,缩进的空格数为4个,不允许使用TAB缩进。 说明:缩进使程序更易阅读,使用空格缩进可以适应不同操作系统与不同开发工具。 规则1.2 分界符(如大括号‘{’和‘}’)应各独占一行,同时与引用它们的语句左对齐。在函数体的开始、类和接口的定义、以及if、for、do、while、switch、case语句中的程序或者static、,synchronized等语句块中都要采用如上的缩进方式。 示例: if (a>b) { doStart(); } 规则1.3 较长的语句、表达式或参数(>80字符)要分成多行书写,长表达式要在低优先级操作符处划分新行,操作符放在新行之首,划分出的新行要进行适当的缩进,使排版整齐,语句可读。 示例: if(logger.isDebugEnabled()) { logger.debug("Session destroyed,call-id" +event.getSession().getCallId()); }
规则1.4 不允许把多个短语句写在一行中,即一行只写一条语句 说明:阅读代码更加清晰 示例:如下例子不符合规范。 Objecto = new Object(); Object b = null; 规则1.5 if, for, do, while, case, switch, default 等语句自占一行,且if, for, do, while, switch等语句的执行语句无论多少都要加括号{},case 的执行语句中如果定义变量必须加括号{}。 说明:读代码更加清晰,减少错误产生 示例: if (a>b) { doStart(); } case x: { int i= 9 } 规则1.6 相对独立的程序块之间、变量说明之后必须加空行。 说明: 阅读代码更加清晰 示例: if(a > b) { doStart(); } //此处是空行 return; 规则1.7 在两个以上的关键字、变量、常量进行对等操作时,它们之间的操作符之前、之后或者前后要加空格;进行非对等操作时,如果是关系密切的立即操作符(如.),后不应加空格。 说明:阅读代码更加清晰
网上资料:共享 Window --> Java --> Code Style --> Code Templates --> Comments --> types --> Edit /** * * 项目名称:${project_name} * 类名称:${type_name} * 类描述: * 创建人:${user} * 创建时间:${date} ${time} * 修改人:${user} * 修改时间:${date} ${time} * 修改备注: * @version * */ ---------------------------------------------------------------------------------------------------------- 设置注释模板的入口:Window->Preference->Java->Code Style->Code Template 然后展开Comments节点就是所有需设置注释的元素啦。现就每一个元素逐一介绍: 文件(Files)注释标签: /** * @Title: ${file_name} * @Package ${package_name} * @Description: ${todo} * @author A18ccms A18ccms_gmail_com * @date ${date} ${time} * @version V1.0 */ 类型(Types)注释标签(类的注释):
/** * @ClassName: ${type_name} * @Description: * @author: 秦天朋 * @date ${date} ${time} * * ${tags} */ 字段(Fields)注释标签: /** * @Fields ${field} : ${todo}(用一句话描述这个变量表示什么) */ 构造函数标签: /** * Title: * Description: * ${tags} */ 方法(Constructor & Methods)标签: /**
javadoc做注释 一. Java 文档 // 注释一行 /* ...... */ 注释若干行 /** ...... */ 注释若干行,并写入javadoc 文档 通常这种注释的多行写法如下: /** * ......... * ......... */ javadoc -d 文档存放目录-author -version 源文件名.java 这条命令编译一个名为“源文件名.java”的java 源文件,并将生成的文档存放在“文档存放目录”指定的目录下,生成的文档中index.html 就是文档的首页。-author 和-version 两个选项可以省略。 二. 文档注释的格式 1. 文档和文档注释的格式化 生成的文档是HTML 格式,而这些HTML 格式的标识符并不是javadoc 加的,而是我们在写注释的时候写上去的。 比如,需要换行时,不是敲入一个回车符,而是写入
,如果要分段,就应该在段前写入。 文档注释的正文并不是直接复制到输出文件(文档的HTML 文件),而是读取每一行后,删掉前导的* 号及* 号以前的空格,再输入到文档的。如 /** * This is first line.
***** This is second line.
This is third line. */ 2. 文档注释的三部分 先举例如下 /** * show 方法的简述. * show 方法的详细说明第一行
* show 方法的详细说明第二行
* @param b true 表示显示,false 表示隐藏 * @return 没有返回值 */ public void show(boolean b) { frame.show(b); } 第一部分是简述。文档中,对于属性和方法都是先有一个列表,然后才在后面一个一个的详细的说明 简述部分写在一段文档注释的最前面,第一个点号(.) 之前(包括点号)。换句话说,就是用第一个点号分隔文档注释,之前是简述,之后是第二部分和第三部分。 第二部分是详细说明部分。该部分对属性或者方法进行详细的说明,在格式上没有什么特殊的要求,可以包含若干个点号。 * show 方法的简述. * show 方法的详细说明第一行
* show 方法的详细说明第二行 简述也在其中。这一点要记住了 第三部分是特殊说明部分。这部分包括版本说明、参数说明、返回值说明等。 * @param b true 表示显示,false 表示隐藏 * @return 没有返回值 三. 使用javadoc 标记 javadoc 标记由“@”及其后所跟的标记类型和专用注释引用组成 javadoc 标记有如下一些: @author 标明开发该类模块的作者 @version 标明该类模块的版本 @see 参考转向,也就是相关主题 @param 对方法中某参数的说明 @return 对方法返回值的说明 @exception 对方法可能抛出的异常进行说明 @author 作者名 @version 版本号 其中,@author 可以多次使用,以指明多个作者,生成的文档中每个作者之间使用逗号(,) 隔开。@version 也可以使用多次,只有第一次有效 使用@param、@return 和@exception 说明方法 这三个标记都是只用于方法的。@param 描述方法的参数,@return 描述方法的返回值,@exception 描述方法可能抛出的异常。它们的句法如下: @param 参数名参数说明 @return 返回值说明
命名规范: 1.所有的标识都只能使用ASCII字母(A-Z或a-z)、数字(0-9)和 下划线”_”。 2.一个唯一包名的前缀总是用全部小写的字母。 3.类名是一个名词,采用大小写混合的方式,每个单词的首字母大 写。 4.接口的大小写规则与类名相似。 5.方法名是一个动词或是动词词组,采用大小写混合的方式,第一 个单词的首字母小写,其后单词的首字母大写。 6.变量名的第一个字母小写,任何中间单词的首字母大写,变量名 应简短且可以顾名思义,易于记忆。避免单个字符的变量名,除非是一次性的临时变量。 7.常量的声明应该全部大写,每个单词之间用”_”连接。 注释规范: 1.注释尽可能使用”//”,对于所有的Javadoc的注释使用/***/,而 临时对代码块进行注释应尽量使用/**/。 2.所有的源文件都应该在开头有一个注释,其中列出文件名、日期 和类的功能概述。每个方法必须添加文档注释(main除外)。 3.每个属性必须加注释。 4.代码中至少包含15%的注释。 5.注释使用中文。
缩进排版规范: 1.避免一行的长度超过60个字符。 2.使用Eclipse源代码的格式化功能完成代码的缩进排版。 文件名规范: 1.一个Java源文件只能储存一个Java类。 2.文件名与Java类相同。 3.一个类文件不超过200行。 声明规范: 1.一行声明一个变量。 2.不要将不同类型变量的声明放在同一行。 3.只在代块的开始处声明变量。 4.所有的变量必须在声明时初始化。 5.避免声明的局部变量覆盖上一级声明的变量。 6.方法与方法直接以空行分隔。 语句规范: 1.每行至少包含一条简单语句。 2.在return语句中,返回值不使用小括号”()”括起来。 3.If月总是用{和}括起来。 4.在for语句的初始化或者更新子句中,避免因使用3个以上变量, 而导致复杂度提高。 5.当switch的一个case顺着往下执行时(因为没有break),通常 应在break语句的位置添加注释。
JAVA代码规范 本Java代码规范以SUN的标准Java代码规范为基础,为适应我们公司的实际需要,可能会做一些修改。本文档中没有说明的地方,请参看SUN Java标准代码规范。如果两边有冲突,以SUN Java标准为准。 1. 标识符命名规范 1.1 概述 标识符的命名力求做到统一、达意和简洁。 1.1.1 统一 统一是指,对于同一个概念,在程序中用同一种表示方法,比如对于供应商,既可以用supplier,也可以用provider,但是我们只能选定一个使用,至少在一个Java项目中保持统一。统一是作为重要的,如果对同一概念有不同的表示方法,会使代码混乱难以理解。即使不能取得好的名称,但是只要统一,阅读起来也不会太困难,因为阅读者只要理解一次。 1.1.2 达意 达意是指,标识符能准确的表达出它所代表的意义,比如:newSupplier, OrderPaymentGatewayService等;而supplier1, service2,idtts等则不是好的命名方式。准确有两成含义,一是正确,而是丰富。如果给一个代表供应商的变量起名是order,显然没有正确表达。同样的,supplier1, 远没有targetSupplier意义丰富。 1.1.3 简洁 简洁是指,在统一和达意的前提下,用尽量少的标识符。如果不能达意,宁愿不要简洁。比如:theOrderNameOfTheTargetSupplierWhichIsTransfered 太长,transferedTargetSupplierOrderName则较好,但是transTgtSplOrdNm就不好了。省略元音的缩写方式不要使用,我们的英语往往还没有好到看得懂奇怪的缩写。 1.1.4 骆驼法则 Java中,除了包名,静态常量等特殊情况,大部分情况下标识符使用骆驼法则,即单词之间不使用特殊符号分割,而是通过首字母大写来分割。比如: supplierName, addNewContract,而不是supplier_name, add_new_contract。
参考文献与注释的编排方法 一、注释的标注方法 注释是对论著正文中某一特定内容的进一步解释或补充说明,以及未公开发表的私人通信、内部资料、书稿和仅有中介文献信息的"转引自"等类文献的引用著录,排印在该页地脚(数字加圆圈,如①、②...)。 二、参考文献的标注方法 参考文献是作者写作论著时所引用的已公开发表的文献书目,或有明确收藏地点的善本、档案,按照在正文中引用的顺序,用数字加方括号集中列表于文末。正文中的标注方法是:1.引用文献原文需要在正文中标出序号与页码(如:"资本主义生产的内在规律在竞争中是以颠倒的形式表现出来的"[1]251),文后参考文献中不出现页码项;2.引用参考文献中的观点可以只标出序号或者序号与页码同时标注(如:生产力决定生产关系[3]);3.文中多次引用同一参考文献内容,在文后参考文献表中只出现一次,其中不注页码;在正文中标注首次引用的文献序号,并在序号的角标外著录引文页码;4.参考文献的编排格式见附注。 例文 国内外现有的竞争理论文献,或者忽略了马克思的竞争理论,或者只把它作为竞争理论发展的一个阶段或众多竞争理论中的一个流派,停留在马克思对市场竞争过程的描述上。然而,马克思指出:"资本主义生产的内在规律在竞争中是以颠倒的形式表现出来的"[1]251。"只有了解了资本的内在本性,才能对竞争进行科学的分析,正像只有认识了天体的实际的、
但又直接感觉不到的运动的人,才能了解天体的表面运动一样。"[2]352 ...... ......而且可以说明,当时政治经济学没有理解的"关于资本主义竞争的基本规律,即调节一般利润率和由它决定的所谓生产价格的规律,也是建立在商品价值和商品成本价格之间的这种差别之上的,建立在由此引起的商品低于价值出售也能获得利润这样一种可能性之上的"[1]45。 ...... ......随着许多偶然的改进,产品系列趋于增大,零件数量趋于增加,会产生大量的多样化成本。[3] 参考文献: [1] 马克思.资本论(第3卷)[M].北京:人民出版社,1975. [2] 马克思.资本论(第1卷)[M].北京:人民出版社,1975. [3] 安德森·派恩二世.21世纪企业竞争的新前沿——大规模定制模式下的敏捷产品开发[M].北京:机械工业出版社,1999. 附注: 一、参考文献著录项目 1. 主要责任者 (专著作者、论文集主编、学位申报人、专利申请人、报告撰写人、期刊文章作者、析出文章作者)。多个责任者之间以","分隔,注意在本项数据中不得出现缩写点"."。主要责任者只列姓名,其后不加"著"、"编"、"主编"、"合编"等责任说明。 2.文献题名; 3.文献类型及载体类型标识;
在软件开发的过程中总是强调注释的规范,但是没有一个具体的标准进行说明,通常都是在代码编写规范中简单的描述几句,不能作为一个代码注释检查的标准和依据,做什么都要有一个依据吗:),现在我特整理了一个《Java的注释规范》,内容来自网络、书籍和自己的实际积累。 JA V A注释规范 版本/状态作者版本日期 1.0 ghc 2008-07-02 一、背景 1、当我们第一次接触某段代码,但又被要求在极短的时间内有效地分析这段代码,我们需要什么样的注释信息? 2、怎么样避免我们的注释冗长而且凌乱不堪呢? 3、在多人协同开发、维护的今天,我们需要怎么样的注释来保证高质、高交的进行开发和维护工作呢? 二、意义 程序中的注释是程序设计者与程序阅读者之间通信的重要手段。应用注释规范对于软件本身和软件开发人员而言尤为重要。并且在流行的敏捷开发思想中已经提出了将注释转为代码的概念。好的注释规范可以尽可能的减少一个软件的维护成本, 并且几乎没有任何一个软件,在其整个生命周期中,均由最初的开发人员来维护。好的注释规范可以改善软件的可读性,可以让开发人员尽快而彻底地理解新的代码。好的注释规范可以最大限度的提高团队开发的合作效率。长期的规范性编码还可以让开发人员养成良好的编码习惯,甚至锻炼出更加严谨的思维能力。 三、注释的原则 1、注释形式统一 在整个应用程序中,使用具有一致的标点和结构的样式来构造注释。如果在其他项目组发现他们的注释规范与这份文档不同,按照他们的规范写代码,不要试图在既成的规范系统中引入新的规范。 2、注释的简洁 内容要简单、明了、含义准确,防止注释的多义性,错误的注释不但无益反而有害。 3、注释的一致性 在写代码之前或者边写代码边写注释,因为以后很可能没有时间来这样做。另外,如果有机会复查已编写的代码,在今天看来很明显的东西六周以后或许就不明显了。通常描述性注释先于代码创建,解释性注释在开发过程中创建,提示性注释在代码完成之后创建。修改代码的同时修改相应的注释,以保证代码与注释的同步。 4、注释的位置 保证注释与其描述的代码相邻,即注释的就近原则。对代码的注释应放在其上方相邻或右方的位置,不可放在下方。避免在代码行的末尾添加注释;行尾注释使代码更难阅读。不过在批注变量声明时,行尾注释是合适的;在这种情况下,将所有行尾注释要对齐。 5、注释的数量 注释必不可少,但也不应过多,在实际的代码规范中,要求注释占程序代码的比例达到20%左右。注释是对代码的“提示”,而不是文档,程序中的注释不可喧宾夺主,注释太多了会让人眼花缭乱,注释的花样要少。不要被动的为写注释而写注释。 6、删除无用注释