在一个软件的生命周期中,绝大多数时间是用来对代码进行维护的,而且软件的生命周期中,会出现很多的人员交替,几乎没有软件一直都是由最初的开发人员来维护的.为了提高软件代码的可读性和软件的可维护性,项目开发过程中必须遵守一致的编码规范。
- 命名规范
包(Packages) 包名使用小写字符com.xxx.xxxxxx
类(Classes) 首字母大写。简洁而富于描述。BaseActivity ThisIsAClassName
接口(Interfaces) 建议接口以大写字母“I”开头。interface IRasterDelegate; interface IStoring;
接口实现类 (implementation) 建议实现类以Impl结尾RasterDelegateImpl
方法(Methods) 首字母小写,其后单词的首字母大写。run(); runFast(); getBackground(); thisIsMethodOrFieldName();
变量(Variables) 所有局部变量,实例变量,类变量,第一个单词的首字母小写,其后单词的首字母大写。
不以下划线或美元符号开头
变量名应简短且富于描述。变量名的选用应该易于记忆,即,能够指出其用途。
尽量避免单个字符的变量名,除非是一次性的临时变量。临时变量通常被取名为i,j,k,m和n,它们一般用于整型;c,d,e,它们一般用于字符型。char c;
int i; float myWidth; thisIsMethodOrFieldName
常量(Constants) 只能包含字母、数字和下划线
第一个字符必须是字母,全部大写
单词间可用下划线隔开static final int MIN_WIDTH = 4;
a) 类,变量,方法命名规范:
- Activity命名规则为:XxxxActivity.java
- Bean命名规则为:BeanXxxx.java
- 布尔值命名规则为:ifXxxx
- TextView命名规则为:txt_Xxx
- EditText命名规则为:edit_Xxx
- ImageView命名规则为:img_Xxx
- Spinner命名规则为:spinner_Xxx
- ListView命名规则为:list_Xxx
- Linearlayout,Realtivelayout等容器命名规则为layout_Xxx
b) XML命名规范
- 一个Activity对应一个XML,命名规则为activity_Activity类名小写.xml
- 共用的XML命名规则include_xxx.xml
- 按钮点击图的xml命名规则为:select_图片名.xml
- ListView使用的xml命名规则为:item_xxx.xml
c) XML中ID命名规范
- TextView的ID命名规则为: txt_Xxx
- EditText的ID命名规则为: edit_Xxx
- ImageView的ID命名规则为: img_Xxx
- Spinner的ID命名规则为: spinner_Xxx
- ListView的ID命名规则为: list_Xxx
- Linearlayout,Realtivelayout等容器的ID命名规则为layout_Xxx
- 其他为定义控件,命名规则为:控件名小写_Xxx
- 能不用ID的则不用ID
d) 图片命名规范
- _9
- ….代码编写
1 包(packages): 采用反域名命名规则,全部使用小写字母。一级包名为com,二级包名为xx(可以是公司或则个人的随便),三级包名根据应用进行命名,四级包名为模块名或层级名
包名 | 此包中包含 |
com.xx.应用名称缩写.activities | 页面用到的Activity类 (activities层级名用户界面层) |
com.xx.应用名称缩写.base | 页面中每个Activity类共享的可以写成一个i额BaseActivity类 (基础共享的类) |
com.xx.应用名称缩写.adapter | 页面用到的Adapter类 (适配器的类) |
com.xx.应用名称缩写.tools | 此包中包含:公共工具方法类(tools模块名) |
com.xx.应用名称缩写.bean (或则 com.xx.应用名称缩写.unity ) | 此包中包含:元素类 |
com.xx.应用名称缩写.db | 数据库操作类 |
com.xx.应用名称缩写.view (或则 com.xx.应用名称缩写.ui ) | 自定义的View类等 |
com.xx.应用名称缩写.service | Service服务 |
com.xx.应用名称缩写.broadcast | Broadcast服务 |
2 类(classes):名词,采用大驼峰命名法,尽量避免缩写,除非该缩写是众所周知的, 比如HTML,URL,如果类名称中包含单词缩写,则单词缩写的每个字母均应大写。
类 | 描述 | 例如 |
activity 类 | Aty或者Activity为后缀标识 | 欢迎页面类WelcomeAty.或者WelcomeActivity |
Adapter类 | Adp或者Adapte 为后缀标识 | 新闻详情适配器NewtDetailAdp或则直接 NewDetailAdapter |
解析类 | Hlr为后缀标识 | 首页解析类HomePosterHlr |
公共方法类 | Tools或Manager为后缀标识 | 线程池管理类:ThreadPoolManager |
数据库类 | 以DBHelper后缀标识 | 新闻数据库:NewDBHelper |
Service类 | 以Service为后缀标识 | 时间服务TimeService |
BroadcastReceive类 | 以Broadcast为后缀标识 | 时间通知TimeBroadcast |
ContentProvider | 以Provider为后缀标识 |
|
直接写的共享基础类 | 以Base开头 | BaseActivity,BaseFragment |
3 接口(interface):命名规则与类一样采用大驼峰命名法,多以able或ible结尾,如interface Runna ble ;
interface Accessible 。
4 方法(methods):动词或动名词,采用小驼峰命名法例如:onCreate(),run()
方法 | 说明 |
initXX() | 初始化相关方法,使用init为前缀标识,如初始化布局initView() |
isXX() | checkXX()方法返回值为boolean型的请使用is或check为前缀标识 |
getXX() | 返回某个值的方法,使用get为前缀标识 |
processXX() | 对数据进行处理的方法,尽量使用process为前缀标识 |
displayXX() | 弹出提示框和提示信息,使用display为前缀标识 |
saveXX() | 与保存数据相关的,使用sav为e前缀标识 |
resetXX() | 对数据重组的,使用reset前缀标识 |
clearXX() | 清除数据相关的 |
removeXXX() | 清除数据相关的 |
drawXXX() | 绘制数据或效果相关的,使用draw前缀标识 |
5 变量(variables)采用小驼峰命名法。类中控件名称必须与xml布局id保持一致。
用统一的量词通过在结尾处放置一个量词,就可创建更加统一的变量,它们更容易理解,也更容易搜索。例如,请使用strCustomerFirst和strCustomerLast,而不要使用strFirstCustomer和strLastCustomer。
量词列表:量词后缀说明
First 一组变量中的第一个
Last 一组变量中的最后一个
Next 一组变量中的下一个变量
Prev 一组变量中的上一个
Cur 一组变量中的当前变量
6 常量(Constants)全部大写,采用下划线命名法.例如:MIN_WIDTH
7 资源文件(图片drawable文件夹下):全部小写,采用下划线命名法,加前缀区分
命名模式:activity名称_逻辑名称/common_逻辑名称
如果有多种形态如按钮等除外如btn_xx.xml(selector)
名称 | 功能 |
btn_xx | 按钮图片使用btn_整体效果(selector) |
btn_xx_normal | 按钮图片使用btn_正常情况效果 |
btn_xx_press | 按钮图片使用btn_点击时候效果 |
bg_head | 背景图片使用bg_功能_说明 |
def_search_cell | 默认图片使用def_功能_说明 |
icon_more_help | 图标图片使用icon_功能_说明 |
seg_list_line | 具有分隔特征的图片使用seg_功能_说明 |
sel_ok | 选择图标使用sel_功能_说明 |
命名后缀:
后缀 | 说明 |
unit | 在使用xml的tilemode来配图片时,element图片使用此后缀 |
nor | 图片的状态,代表普通状态 |
hl | 图片的状态,代表高亮状态 |
press | 图片的状态,代表按下状态 |
select | 图片的状态,代表其所占的view被选中 |
unselect | 图片的状态,代表其所占的view没有被选中 |
8 资源布局文件(XML文件(layout布局文件)):
全部小写,采用下划线命名法
1).contentview命名, Activity默认布局,以去掉后缀的Activity类进行命名。不加后缀:
功能模块.xml
例如:main.xml、more.xml、settings.xml
或则:activity_功能模块.xml例如:activity_main.xml、activity_more.xml
2).Dialog命名:dialog_描述.xml
例如:dlg_hint.xml
2).PopupWindow命名:ppw_描述.xml
例如:ppw _info.xml
3). 列表项命名listitem_描述.xml
例如:listitem_city.xml
4).包含项:include_模块.xml
例如:include_head.xml、include_bottom.xml
5).adapter的子布局:功能模块_item.xml
例如:main_item.xml、
9 动画文件(anim文件夹下):全部小写,采用下划线命名法,加前缀区分。
//前面为动画的类型,后面为方向
动画命名例子 | 规范写法 | 备注 |
fade_in | 淡入 |
|
fade_out | 淡出 |
|
push_down_in | 从下方推入 |
|
push_down_out | 从下方推出 |
|
push_left | 推像左方 |
|
slide_in_from_top | 从头部滑动进入 |
|
zoom_enter | 变形进入 |
|
slide_in | 滑动进入 |
|
shrink_to_middle | 中间缩小 |
|
10 资源ID(resourcesid):大小写规范与方法名一致,采用小驼峰命名法。命名规范为“资源控件的缩写 名”+“变量名”。注意:页面控件名称应该和控件id名保持一致
strings.xml,colors.xml等中的id命名:
命名模式:activity名称_功能模块名称_逻辑名称/activity名称_逻辑名称/common_逻辑名称
strings.xml中,使用activity名称注释,将文件内容区分开来
11 layout中的id命名
命名模式为:view缩写_模块名称_view的逻辑名称
view的缩写详情如下:
控件 | 缩写 |
LayoutView | lv |
RelativeView | rv |
TextView | tv |
Button | btn |
ImageButton | imgBtn |
ImageView | mgView 或则 iv |
CheckBox | chk |
RadioButton | rdoBtn |
analogClock | anaClk |
DigtalClock | dgtClk |
DatePicker | dtPk |
EditText | edtTxt |
TimePicker | tmPk |
toggleButton | tglBtn |
ProgressBar | proBar |
SeekBar | skBar |
AutoCompleteTextView | autoTxt |
ZoomControls | zmCtl |
VideoView | vdoVi |
WdbView | webVi |
RantingBar | ratBar |
Tab | tab |
Spinner | spn |
Chronometer | cmt |
ScollView | sclVi |
TextSwitch | txtSwt |
ImageSwitch | imgSwt |
listView | lVi 或则lv |
ExpandableList | epdLt |
MapView | mapVi |
12.activity中的view变量命名
命名模式为:逻辑名称+view缩写
建议:如果layout文件很复杂,建议将layout分成多个模块,每个模块定义一个moduleViewHolder,其成员变量包含所属view
13.styles.xml:将layout中不断重现的style提炼出通用的style通用组件,放到styles.xml中;
14.使用layer-list和selector
- 注释
- 为了便于理解和维护,源代码中要加入必要的注释,如关键的算法,模块接口的定等。注释的地方按模块重要程度等级应包括类、变量、方法、方法里的代码以及作者信息
- Java程序有两类注释:实现注释(implementationcomments)和文档注释(document comments)。文档注释(被称为"DocComments")是Java独有的,并由/**...*/界定。文档注释可以通过javadoc工具转换成HTML文件。
- 程序可以有4种实现注释的风格:块(block)、单行(single-line)、尾端(trailing)和行末(end-of-line)
- 在每个程序的最开始部分,一般都用Javadoc(即文档注释)注释对程序的总体描述以及版权信息,之后在主程序中 可以为每个类、接口、方法、字段添加 Javadoc注释,每个注释的开头部分先用一句话概括该类、接口、方法、字段所完成的功能,这句话应单独占据一行以突出其概括作用,在这句话后面可以跟随更加详细的描述段落。在描述性段落之后还可以跟随一些以Javadoc注释标签开头的特殊段落,例如上面例子中的@auther和@version,这 些段落将在生成文档中以特定方式显示。
- Javadoc注释是一种多行注释,以/**开头,而以*/结束,注释可以包含一些 HTML标记符和专门的关键词。使用Javadoc 注释的好处是编写的注释可以被自动转为在线文档,省去了单独编写程序文档的麻烦。
例如:
/**
* This is an example of
* Javadoc
* @author XXX
* @version 0.1, 02/22/2012
*/
package test;
importjava.io.Serializable;
/**
* "人"对象,拥有三个属性,分别是名字,性别,年龄。
* @version 1.0, 2012-12-12
* @author张三
*/
publicclass Person implements Serializable {
privatestatic finallong serialVersionUID = 1L;
/**男性,值为{@value} */
publicstatic finalint MALE = 1;
/**女性,值为{@value} */
publicstatic finalint FEMALE= 2;
/**名字 */
protected Stringname;
/**年龄 */
protectedint sex;
/**
*构造一个Person实例。设定Person的名字和性别。
*@param name String名字
*@param sexint 性别,有效值是{@link #MALE男性}和{@link #FEMALE}
*@throws PersonArgumentException
*/
public Person(String name,int sex){
if (sex !=MALE && sex != FEMALE){
this.name = name;
this.sex = sex;
}
}
/**
*获取性别代号。
*@returnint
*@see MALE
*@see FEMALE
*/
publicint getSex() {
returnsex;
}
/**
*设置性别
*@param sexint
*/
publicvoid setSex(int sex) {
this.sex = sex;
}
}
所有的Javadoc注释均以/**开始,以*/结束,每个注释包含一些描述性的文本及若干个Javadoc标签。描述性的文本不但可以用平面文本,还可以使用HTML文本;Javadoc标签一般以"@"为前缀,有的也以"{@"为前缀,以"}"结束,如{@value}。
上述文档注释生成Javadoc文档后的显示样式如下所示:
public class Person
extends java.lang.Object
implements java.io.Serializable
"人"对象,拥有三个属性,分别是名字,性别,年龄。
版本:
1.0, 2012-12-12
作者:
张三
另请参见:
|
|
|
|
构造方法摘要 | |
|
方法摘要 | |
|
|
|
|
从类 java.lang.Object 继承的方法 |
|
以后我们项目开发中,要求大家认真详细的做javadoc,每当项目有重要更新,我们会同时更新javadoc,以方便所有参与人员都能对整个项目进行全面而清晰的了解,查阅.
JavaDoc标识符表
标签 | 说明 | JDK 1.1 doclet | 标准doclet | 标签类型 |
@author 作者 | 作者标识 | √ | √ | 包、 类、接口 |
@version 版本号 | 版本号 | √ | √ | 包、 类、接口 |
@param 参数名 描述 | 方法的入参名及描述信息,如入参有特别要求,可在此注释。 | √ | √ | 构造函数、 方法 |
@return 描述 | 对函数返回值的注释 | √ | √ | 方法 |
@deprecated 过期文本 | 标识随着程序版本的提升,当前API已经过期,仅为了保证兼容性依然存在,以此告之开发者不应再用这个API。 | √ | √ | 包、类、接口、值域、构造函数、 方法 |
@throws异常类名 | 构造函数或方法所会抛出的异常。 | √ | 构造函数、 方法 | |
@exception 异常类名 | 同@throws。 | √ | √ | 构造函数、 方法 |
@see 引用 | 查看相关内容,如类、方法、变量等。 | √ | √ | 包、类、接口、值域、构造函数、 方法 |
@since 描述文本 | API在什么程序的什么版本后开发支持。 | √ | √ | 包、类、接口、值域、构造函数、 方法 |
{@link包.类#成员 标签} | 链接到某个特定的成员对应的文档中。 | √ | 包、类、接口、值域、构造函数、 方法 | |
{@value} | 当对常量进行注释时,如果想将其值包含在文档中,则通过该标签来引用常量的值。 | √(JDK1.4) | 静态值域 |
此外还有@serial、@serialField、@serialData、{@docRoot}、{@inheritDoc}、{@literal}、{@code} {@value arg}几个不常用的标签,感兴趣者请自行学习.
实现注释通常用于提供对文件,方法,数据结构和算法的描述。实现注释被置于每个文件的开始处以及每个方法之前。它们也可以被用于其他地方,比如方法内部。在功能和方法内部的实现注释应该和它们所描述的代码具有一样的缩进格式。实现注释之首应该有一个空行,用于把实现注释和代码分割开来,比如:
l 多行注释
/*
* Here is a block comment line1.
* Here is a block comment line2.
*/
l 单行注释
短注释可以显示在一行内,并与其后的代码具有一样的缩进层级。如果一个注释不能在一行内写完,就该采用块注释。单行注释之前应该有一个空行。以下是一个Java代码中单行注释的例子:
if (condition) {
/* Handle the condition. */
...
}
l 尾端注释
极短的注释可以与它们所要描述的代码位于同一行,但是应该有足够的空白来分开代码和注释。若有多个短注释出现于大段代码中,它们应该具有相同的缩进。
以下是一个Java代码中尾端注释的例子(注意它们的缩进):
if (a == 2) {
return TRUE; /*special case */
} else {
return method(a); /*works only for odd a */
}
l 行末注释
注释界定符"//",可以注释掉整行或者一行中的一部分。它一般不用于连续多行的注释文本;然而,它可以用来注释掉连续多行的代码段。以下是所有三种风格的例子:
if (foo> 1) {
// Do a double-flip.
...
}else {
return false; // Explain why here.
}
//if (bar> 1) {
//
// // Do a triple-flip.
// ...
//}
//else{
// return false;
- 一些良好的编码思想和编码习惯
- 松耦合,高聚合.
- 消除所有警告(重要)
- 局部对象变量使用后复位为null
- 只使用简单的表达式
- 相同逻辑代码出现两次以上,考虑是否可以做成方法
- 用()使操作符优先级明确化
- 避免使用java.util.Vector
- 不要在if条件里面附值
- 单个的循环、条件语句也加{}
- has/can/is前缀的方法返回布尔型值
- 不要再catch()块里什么代码也不放
- 每行只声明一个变量
- 变量在定义的同时初始化
- 单个变量只做单个用途
- 让一切东西都尽可能地“私有”——private。
- 从旁观者和使用者角度来多次审核自己的代码
- 每个System.out.println方法,至少使用1.3ms.
- 尽可能细致地加上注释,并用javadoc注释文档语法生成自己的程序文档。
- 大量引用padding的布局,永远无法适应所有手机屏幕.
- 永远不要在Map对象使用迭代遍历过程中做增减元素操作
- 项目中不要有相同名称的类,即使他们的包名不同.编译器也可能先找到同名的另一个类.
- 覆盖父类的方法时,保证使用@override关键字,来编码由于拼写错误,而导致的方法没有成功覆盖
- 字符串连接时StringBuffer的append方法比String+String的方式效率提高8倍以上, 在没有同步性要求时StringBuilder比StringBuffer更加高效.
- 优秀的代码远没有稳定的软件重要.编码过程中,我们宁愿选择一段很长,效率低但能保证软件稳定运行的代码,而不选择一段短,效率高但却有可能带来不稳定性的代码.
- 对一些习惯于顺序编程思维、且初涉OOP领域的新手,往往喜欢先写一个顺序执行的程序,再把它嵌入一个或两个巨大的对象里。时刻提醒自己,不要让程序变成一条流水线.
- 避免使用“魔术数字”,代码中用到的数字,应为他创建一个变量,并为其使用具有说服力的描述性名称,这样可使程序更易理解以及更易维护。
- 构造方法中只进行对象的初始化工作。尽可能地避免调用其他方法,因为那些方法可能被其他人覆盖或取消,从而在构建过程中产生不可预知的结果.
- 用继承及方法覆盖来表示行为间的差异,而用字段表示状态间的区别。比如用多个类继承Color类来表示颜色,这是绝对要避免的:应直接在Color类中使用一个“颜色”字段。
- 对浮点数值的相等判断是否是恰当的?(严禁使用==直接判断)本来应该相等的两个浮点数由于CPU的不同实现,用==就会认为它们不等。应该使用两个浮点数之间的差异的绝对值小于某个可以接受的值来判断判断它们是否相等,比如用
if (fabs(fa-fb) < 0.000001)
来代替
if (fa == fb)
- 方法体里面定义了input或者output流的话,需要在finally里面把它关掉。以下这几种调用不需要遵守这条规则,因为colse()方法不起作用:
java.io.StringWriter
java.io.ByteArrayOutputStream
java.io.ByteArrayInputStream
- 不要使用’\n’或者'\r'来分行这两个标记看来很普遍,特别是’\n’。我们经常用来作为分行用。但是不同的系统用不同的分行字符. 我们可以用其它的一些方法来代替,比如println(),这个方法在不同的系统平台上都起到相同的作用.
如System.out.println("Hello\n" + name);写成
char c=System.getProperty("line.separator");
System.out.println("Hello"+c +name);
这里面有自己的一些总结,也有参考一些别人的想法,总之养成良好的编码习惯和命名规范,对于自己和整个团队都有好处。