华为Android平台Java编程规范.docx
- 文档编号:9618110
- 上传时间:2023-02-05
- 格式:DOCX
- 页数:34
- 大小:51.21KB
华为Android平台Java编程规范.docx
《华为Android平台Java编程规范.docx》由会员分享,可在线阅读,更多相关《华为Android平台Java编程规范.docx(34页珍藏版)》请在冰豆网上搜索。
华为Android平台Java编程规范
Android平台Java编程规范
(文档编号/IPD-CMMIV1.3/仅供内部使用)
拟制:
刘祥根l00137202
日期:
2008-12-24
审核:
各DU软件团队
日期:
2011-10-18
批准:
软件平台
日期:
2011-10-18
HuaweiTechnologiesCo.,Ltd.
华为技术有限公司
Allrightsreserved
版权所有XX
DKBA
华为技术有限公司企业技术规范
DKBA1040-2008.12
Android平台Java编程规范
2008-12-24发布2008-12-25实施
Revisionrecord修订记录
Date
日期
Revisionversion
修订版本
CRID/DefectID
CR号
SectionNumber
修改
章节
Description
描述
Author
作者
2011-7-4
1.1
修改以更适应android
Xubaoshun
2011-9-30
1.2
参考公司已有规范、业界规范和代码静态检查工具规范进行补充和修订
张明修
前言
本规范是参考公司的《软件编程规范总则》《Java编程规范》,SUN公司《JavaCodingStyleGuide》、Google的《CodeStyleGuidelinesforContributorsAndroidOpenSource》,在原有《U8220Android编程规范》基础上修改形成《Android平台Java编程规范》。
本规范没有涉及到的相关部分,请参见《软件编程规范总则》和公司的《Java编程规范》。
Android平台Java编程规范
范围
本规范规定了使用AndroidJava语言编程时排版、注释、命名、编码和JTEST的规则和建议。
本规范适用于使用Android平台Java语言编程的部门和产品。
规范性引用文件
下列文件中的条款通过本规范的引用而成为本规范的条款。
凡是注日期的引用文件,其随后所有的修改单(不包括勘误的内容)或修订版均不适用于本规范,然而,鼓励根据本规范达成协议的各方研究是否可使用这些文件的最新版本。
凡是不注日期的引用文件,其最新版本适用于本规范。
序号
编号
名称
1
《软件编程规范总则》同总则的部分使用*号
术语和定义
规则:
编程时强制必须遵守的原则。
建议:
编程时必须加以考虑的原则。
格式:
对此规范格式的说明。
说明:
对此规范或建议进行必要的解释。
示例:
对此规范或建议从正、反两个方面给出例子。
排版规范
4.1.规则
1.1.1*缩进风格
程序块要采用缩进风格编写,缩进的空格数为4个。
说明:
对于由开发工具自动生成的代码可以有不一致。
1.1.2分界符‘{’和‘}’
应与所修改文件或新建文件所在工程或模块保持一致。
Android中要求分界符‘{’不独占一行,和前面一个语句于同一列。
分界符‘}’独占一行,引用它们的语句左对齐。
在函数体的开始、类和接口的定义、以及if、for、do、while、switch、case语句中的程序都要采用如上的缩进方式。
示例:
如下例子不符合规范。
for(...)
{
...//programcode
}
if(...)
{
...//programcode
}
voidexample_fun(void)
{
...//programcode
}
应如下书写。
for(...){
...//programcode
}
voidexample_fun(void){
...//programcode
}
1.1.3*较长的语句、表达式或参数
较长的语句、表达式或参数(>100字符)要分成多行书写,长表达式要在低优先级操作符处划分新行,操作符放在新行之首,划分出的新行要进行适当的缩进,使排版整齐,语句可读。
示例:
if(filename!
=null
&&newFile(logPath+filename).length() { ...//programcode } publicstaticLogIteratorread(StringlogType,DatestartTime,DateendTime,intlogLevel,StringuserName,intbufferNum) 1.1.4*不允许把多个短语句写在一行中 不允许把多个短语句写在一行中,即一行只写一条语句示例: 如下例子不符合规范: LogFilenamenow=null;LogFilenamethat=null; 应如下书写: LogFilenamenow=null; LogFilenamethat=null; 1.1.5*if,for,do,while,case,switch,default等语句自占一行, if,for,do,while,case,switch,default等语句自占一行,且if,for,do,while等语句的执行语句无论多少都要加括号{}。 示例: 如下例子不符合规范。 if(writeToFile)writeFileThread.interrupt(); 应如下书写: if(writeToFile){ writeFileThread.interrupt(); } 1.1.6*相对独立的程序块之间、变量说明之后必须加空行。 示例,如下例子不符合规范: if(log.getLevel() { return; } LogWriterwriter; 应如下书写: if(log.getLevel() { return; } LogWriterwriter; intindex; 1.1.7*对齐只使用空格键,不使用TAB键。 (TAB键长度为4个空格) 说明: 以免用不同的编辑器阅读程序时,因TAB键所设置的空格数目不同而造成程序布局不整齐。 JBuilder、UltraEdit等编辑环境,支持行首TAB替换成空格,应将该选项打开。 1.1.8*关键字、变量、常量进行对等操作 在两个以上的关键字、变量、常量进行对等操作时,它们之间的操作符之前、之后或者前后要加空格;进行非对等操作时,如果是关系密切的立即操作符(如.),后不应加空格。 说明: 采用这种松散方式编写代码的目的是使代码更加清晰。 由于留空格所产生的清晰性是相对的,所以,在已经非常清晰的语句中没有必要再留空格,如果语句已足够清晰则括号内侧(即左括号后面和右括号前面)不需要加空格,多重括号间不必加空格,因为在Java语言中括号已经是最清晰的标志了。 在长语句中,如果需要加的空格非常多,那么应该保持整体清晰,而在局部不加空格。 给操作符留空格时不要连续留两个以上空格。 示例: Ø逗号、分号只在后面加空格。 inta,b,c; Ø比较操作符,赋值操作符"="、"+=",算术操作符"+"、"%",逻辑操作符"&&"、 "&",位域操作符"<<"、"^"等双目操作符的前后加空格。 if(current_time>=MAX_TIME_VALUE)a=b+c;a*=2;a=b^2; Ø"! "、"~"、"++"、"--"、"&"(地址运算符)等单目操作符前后不加空格。 flag=! isEmpty;//非操作"! "与内容之间i++;//"++","--"与内容之间 Ø"."前后不加空格。 p.id=pid;//"."前后不加空格 Øif、for、while、switch等与后面的括号间应加空格,使if等关键字更为突出、明显。 1.2建议 1.2.1交叉放置 类属性和类方法不要交叉放置,不同存取范围的属性或者方法也尽量不要交叉放置。 类格式定义: { 类的公有属性定义 类的保护属性定义 类的私有属性定义 类的公有方法定义 类的保护方法定义 类的私有方法定义 } 注释规范 1.3规则 1.3.1注释量 一般情况下,源程序有效注释量必须在30%以上。 说明: 注释的原则是有助于对程序的阅读理解,在该加的地方都加了,注释不宜太多也不能太少,注释语言必须准确、易懂、简洁。 可以用注释统计工具来统计。 1.3.2包的注释 包的注释写入一个名为package.html的HTML格式的说明文件放入当前路径。 说明: 方便JavaDoc收集示例: com/huawei/android/mms/ui/package.html。 1.3.3包注释内容 简述本包的作用、详细描述本包的内容、产品模块名称和版本、公司版权。 说明: 在详细描述中应该说明这个包的作用以及在整个项目中的位置。 格式如下: 一句话简述 详细描述 产品模块名称和版本 示例: 为WEBSMAP提供通信类,上层业务使用本包的通信类与SMP-B进行通信。 详细描述。 。 。 。 。 。 。 。 IINV100R001WEBSMAP 1.3.4文件注释 文件注释写入文件头部,包名之前的位置。 说明: 注意以/*开始避免被JavaDoc收集示例: /* Copyright©,1988-2009,HuaweiTech.Co.,Ltd. Author: Date: //作者、版本及完成日期 Description: //用于详细说明此程序文件完成的主要功能,与其他模块 //或函数的接口,输出值、取值范围、含义及参数间的控 //制、顺序、独立或依赖等关系 Others: //其它内容的说明 */ 1.3.5类和接口注释 类和接口注释放在package关键字之后,class或者interface关键字之前。 这样可以方便JavaDoc收集。 示例如下: packagecom.huawei.android.mms.ui; /** *注释内容 */ publicclassCommManager 1.3.6类和接口的注释内容 类的注释主要是一句话功能简述、功能详细描述,说明: 可根据需要列出: 版本号、生成日期、作者、内容、功能、与其它类的关系等。 如果一个类存在Bug,请如实说明这些Bug。 格式如下: /** *〈一句话功能简述〉 *〈功能详细描述〉 *@author[作者] *@version[版本号,YYYY-MM-DD] *@see[相关类/方法] *@since[产品/模块版本] *@deprecated */ 说明: 描述部分说明该类或者接口的功能、作用、使用方法和注意事项,每次修改后增加作者和更新版本号和日期,@since表示从那个版本开始就有这个类或者接口,@deprecated表示不建议使用该类或者接口。 示例: /** *LogManager类集中控制对日志读写的操作。 *全部为静态变量和静态方法,对外提供统一接口。 分配对应日志类型的读写器, *读取或写入符合条件的日志纪录。 *@author张三,李四,王五 *@version1.2,2001-03-25 *@seeLogIteraotor *@seeBasicLog *@sinceCommonLog1.0 */ 1.3.7类属性、公有和保护方法注释 类属性、公有和保护方法注释写在类属性、公有和保护方法上面。 示例: /** *注释内容 */ privateStringlogType; /** *注释内容 */ publicvoidwrite() 1.3.8成员变量注释内容 成员变量注释内容包括成员变量的意义、目的、功能,可能被用到的地方。 公有和保护方法注释内容: 列出方法的一句话功能简述、功能详细描述、输入参数、输出参数、返回值、违例等。 格式: /** *〈一句话功能简述〉 *〈功能详细描述〉 *@param[参数1][参数1说明] *@param[参数2][参数2说明] *@return[返回类型说明] *@exception/throws[违例类型][违例说明] *@see[类、类#方法、类#成员] *@deprecated*/ 说明: @since表示从那个版本开始就有这个方法;@exception或throws列出可能仍出的异常;@deprecated表示不建议使用该方法。 示例: /** *根据日志类型和时间读取日志。 *分配对应日志类型的LogReader,指定类型、查询时间段、条件和反复器缓冲数, *读取日志记录。 查询条件为null或0的表示没有限制,反复器缓冲数为0读不到日志。 *查询时间为左包含原则,即[startTime,endTime)。 *@paramlogTypeName日志类型名(在配置文件中定义的) *@paramstartTime查询日志的开始时间 *@paramendTime查询日志的结束时间 *@paramlogLevel查询日志的级别 *@paramuserName查询该用户的日志 *@parambufferNum日志反复器缓冲记录数 *@return结果集,日志反复器 *@sinceCommonLog1.0 */ publicstaticLogIteratorread(StringlogType,DatestartTime,DateendTime,intlogLevel,StringuserName,intbufferNum) 1.3.9异常抛出 对于方法内部用throw语句抛出的异常,必须在方法的注释中标明,对于所调用的其他方法所抛出的异常,选择主要的在注释中说明。 对于非RuntimeException,即throws子句声明会抛出的异常,必须在方法的注释中标明。 说明: 异常注释用@exception或@throws表示,在JavaDoc中两者等价,但推荐用@exception标注Runtime异常,@throws标注非Runtime异常。 异常的注释必须说明该异常的含义及什么条件下抛出该异常。 1.3.10*注释与代码放置 注释应与其描述的代码相近,对代码的注释应放在其上方或右方(对单条语句的注释)相邻位置,不可放在下面,如放于上方则需与其上面的代码用空行隔开。 1.3.11*注释与描述内容的缩排 注释与所描述内容进行同样的缩排。 说明: 可使程序排版整齐,并方便注释的阅读与理解。 示例: 如下例子,排版不整齐,阅读稍感不方便。 publicvoidexample(){ //注释 CodeBlockOne //注释 CodeBlockTwo } 应改为如下布局。 publicvoidexample() { //注释 CodeBlockOne //注释 CodeBlockTwo } 1.3.12*将注释与其上面的代码用空行隔开 示例: 如下例子,显得代码过于紧凑。 //注释programcodeone//注释programcodetwo 应如下书写: //注释 programcodeone //注释 programcodetwo 1.3.13*对变量的定义和分支语句(条件分支、循环语句等)必须编写注释 说明: 这些语句往往是程序实现某一特定功能的关键,对于维护人员来说,良好的注释帮助更好的理解程序,有时甚至优于看设计文档。 1.3.14*switch语句下的case语句 对于switch语句下的case语句,如果因为特殊情况需要处理完一个case后进入下一个case处理,必须在该case语句处理完、下一个case语句前加上明确的注释。 说明: 这样比较清楚程序编写者的意图,有效防止无故遗漏break语句。 1.3.15*注释的管理 边写代码边注释,修改代码同时修改相应的注释,以保证注释与代码的一致性。 不再有用的注释要删除。 1.3.16*注释的内容 注释的内容要清楚、明了,含义准确,防止注释二义性。 说明: 错误的注释不但无益反而有害。 1.3.17*注释中的缩写 避免在注释中使用缩写,特别是不常用缩写。 说明: 在使用缩写时或之前,应对缩写进行必要的说明。 1.3.18注释语言 注释应该使用英语和半角标点符号,否则编译中会出现大量乱码,影响编译问题定位。 1.3.19删除代码的注释 删除代码,特别是删除多行代码、删除方法、成员变量等需要有明确注释,便于版本升级;删除android原始代码必须要求有明确注释。 注释需包含删除原因,删除的方法、成员名,必要时需注明删除的代码行数。 1.4建议 1.4.1*注释不应该出现在代码行中 避免在一行代码或表达式的中间插入注释。 说明: 除非必要,不应在代码或表达中间插入注释,否则容易使代码可理解性变差。 1.4.2*代码行其实也是注释 通过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结构,使代码成为自注释的。 说明: 清晰准确的函数、变量等的命名,可增加代码可读性,并减少不必要的注释。 1.4.3*在代码的功能、意图层次上进行注释,提供有用、额外的信息。 说明: 注释的目的是解释代码的目的、功能和采用的方法,提供代码以外的信息,帮助读者理解代码,防止没必要的重复注释信息。 示例: 如下注释意义不大。 //如果receiveFlag为真if(receiveFlag) 而如下的注释则给出了额外有用的信息。 //如果从连结收到消息 if(receiveFlag) 1.4.4*在程序块的结束行右方加注释标记,以表明某程序块的结束。 说明: 当代码段较长,特别是多重嵌套时,这样做可以使代码更清晰,更便于阅读。 示例: 参见如下例子。 if(...) { programcode1 while(index programcode2 }//endofwhile(index }//endofif(...)//指明是哪条if语句结束 1.4.5*注释使用一种语言 注释应考虑程序易读及外观排版的因素。 说明: 注释语言不统一,影响程序易读性和外观排版,出于对维护人员的考虑,建议使用中文。 1.4.6方法内的注释使用//,问题单注释也必须使用//,详见8.1.2 说明: 调试程序的时候可以方便的使用/*。 。 。 */注释掉一长段程序。 1.4.7注释应该简洁明了 方法和类描述的第一句话尽量使用简洁明了语句概括功能,然后加以句号。 接下来的部分可以详细描述。 说明: JavaDoc工具收集简介的时候使用选取第一句话。 1.4.8顺序实现流程的说明使用1、2、3、4在每个实现步骤部分的代码前面进行注释。 示例: 如下是对设置属性的流程注释 //1、判断输入参数是否有效。 //2、设置本地变量。 1.4.9一些复杂的代码需要说明 示例: 这里主要是对闰年算法的说明。 //1.如果能被4整除,是闰年; //2.如果能被100整除,不是闰年; //3.如果能被400整除,是闰年。 命名规范 1.5规则 1.5.1包名 完全自己开发的包,包名采用域后缀倒置的加上自定义的包名,采用小写字母。 包命名格式需要采取如下格式: com.huawei.android.模块名 com.huawei.android.模块名.小模块名 对于修改的代码,一律保持原先的包名不变化。 1.5.2类名和接口名 使用类意义完整的英文描述,每个英文单词的首字母使用大写、其余字母使用小写的大小写混合法。 示例: OrderInformation,CustomerList,LogManager,LogConfig,SmpTransaction。 1.5.3方法名 使用意义完整的英文描述: 第一个单词的字母使用小写、剩余单词首字母大写其余字母小写的大小写混合法。 示例: privatevoidcalculateRate(); publicvoidaddNewOrder(); 1.5.4方法get和set 存取属性的方法采用setter和getter方法,动作方法采用动词和动宾结构。 格式: get+非布尔属性名()is+布尔属性名()set+属性名()动词()动词+宾语()示例: publicStringgetType(); publicbooleanisFinished(); publicvoidsetVisible(boolean); publicvoidshow(); publicvoidaddKeyListener(Listener); 1.5.5属性名 属性名使用意义完整的英文描述: 第一个单词必须是小写字母m(member的意思)、剩余单词首字母大写其余字母小写的大小写混合法。 属性名不能与方法名相同。 命名规范示例: privatemCustomerName; privatemOrderNumber; privatemSmpSession; 1.5.6常量名 使用全大写的英文描述,英文单词之间用下划线分隔开,并且使用finalstatic修饰 示例: publicfinalstaticintMAX_VALUE=1000; publicfinalstaticStringDEFAULT_START_DATE="2001-12-08"; 1.5.7属性名约定 属性名不可以和公有方法参数相同,如果相同,需要使用this来表示成员变量。 属性名不能和局部变量相同。 引用静态成员变量时使用类名引用。 即使是在类内部使用,静态成员变量也需要使用类名进行引用。 示例如下: publicclassPerson{ privateStringmName; privatestaticListPROPERTIES; publicvoidsetName(Stringname){ mName=name; } publicvoidsetProperties(Listpro
公司版权信息
(C)版权所有2008-2009华为技术有限公司
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- 华为 Android 平台 Java 编程 规范
![提示](https://static.bdocx.com/images/bang_tan.gif)