#BD601 APP 开发规范文档 ###written by wangkuan 20160918#
1.android开发准备
- 开发环境使用android studio
- 安装.ignore(配合git使用) codeglance(代码预览) markdown surport(md文件支持)这三款插件
- 采用markdown记录开发中的各种问题
- 务必在使用git前在项目根目录中添加.gitignore文件(用.ignore插件生成)
2.开发规定
2.1文件编码
源文件编码格式为 UTF-8
2.2命名规范
- 类名 采用大驼峰驼峰命名法,即功能名+类型名的方式来命名类名及方法名
类 | 命名格式 | 示例 |
---|---|---|
Activity | XXX功能+Activity | 如主界面HomeActivity,启动页LauncherActivity |
Service | XXX功能+Service | 如消息推送的Service,PushService或PushMessageService |
BroadcastReceiver | XXX功能+Receiver | 如在线的消息广播接受者,OnlineReceiver |
ContentProvider | XXX功能+Provider | 如联系人的内容提供者,ContactsProvider |
Fragment | XXX功能+Fragment | 如显示联系人的Fragment,ContactsFragment |
Dialog | XXX功能+Dialog | 如普通的选择提示对话框,ChoiceDialog |
Adapter | XXX功能+XX类型控件Adapter | 如联系人列表,ContactsListAdapter |
基础功能类 | Base+XX父类名 | 如BaseActivity,BaseFragment |
工具类 | XXX功能+Utils | 如处理字符串的工具类,StringUtils |
管理类 | XXX功能+Manager | 如管理联系人的类,ContactsManager |
- 接口命名 和类名基本一致。也可以在接口名前面再加一个大写的I,表明这是一个接口Interface。如:可以表明一个信息是否可以分享的接口,可以命名为Shareable,也可以是IShareable。
- 方法名 动词或动名词,采用小驼峰命名法
命名风格 | 含义 |
---|---|
initXX() | 初始化,如初始化所有控件initView() |
isXX() | 是否满足某种要求,如是否为注册用户isRegister() |
processXX() | 对数据做某些处理,可以以process作为前缀 |
displayXX() | 显示提示信息,如displayXXDialog,displayToast,displayXXPopupWindow |
saveXX() | 保存XX数据 |
resetXX() | 重置XX数据 |
addXX()/insertXX() | 添加XX数据 |
deleteXX()/removeXX() | 删除XX数据 |
updateXX() | 更新XX数据 |
searchXX()/findXX()/queryXX() | 查找XX数据 |
draw() | 控件里面使用居多,例如绘制文本drawText |
-
变量 采用小驼峰命名法
- 非公有,非静态成员变量命名前面加m(member,表示成员变量之意),如,控件的宽高 mWidth,mHeight
- 静态类变量前面加s(static,表示静态变量之意),如,一个静态的单例 sSingleInstance
- 公有非静态字段命名以p开头
- 公有静态字段(全局变量)命名以g开头
- 局部变量名
- 局部变量名以LowerCamelCase风格编写,比起其它类型的名称,局部变量名可以有更为宽松的缩写。
- 虽然缩写更宽松,但还是要避免用单字符进行命名,除了临时变量和循环变量。
- 即使局部变量是final和不可改变的,也不应该把它示为常量,自然也不能用常量的规则去命名它。
- 临时变量
- 临时变量通常被取名为i,j,k,m和n,它们一般用于整型;c,d,e,它们一般用于字符型。如: for (int i = 0; i < len ; i++),并且它和第一个单词间没有空格。
-
布局文件名称的定义必须为小写字母,否者无法生成R类,尽量不要用缩写。以表达清楚该文件用途为本,通常情况下用下划线连接各语义单词 例如dialog_title_icons.xml 或者list_menu_item_checkbox.xml
-
包命名 采用反域名命名规则,全部使用小写字母 例如:com.beidou.bd601.activity
- 一级包名为com;
- 二级包名为xx(可以是公司或则个人的随便);
- 三级包名应用的英文名app_name;
- 四级包名为模块名或层级名;
-
常量 全部大写,采用下划线命名法.如:MIN_WIDTH,MAX_SIZE
-
布局资源文件 全部小写,采用下划线命名法
布局类型 | 命名风格 |
---|---|
Activity的xml布局 | activity_+XX功能,如主页面activity_home |
Fragment的xml布局 | fragment_+XX功能,如联系人模块fragment_contacts |
Dialog的xml布局 | dialog_+XX功能,如选择日期dialog_select_date |
抽取出来复用的xml布局(include) | include_+XX功能,如底部tab栏include_bottom_tabs |
ListView或者RecyclerView的item xml布局 | XX功能+_list_item,如联系人的contact_info_list_item |
GridView的item xml布局 | XX功能+_grid_item,如相册的album_grid_item |
- 动画资源文件(anim文件夹下) 全部小写,采用下划线命名法,加前缀区分-
动画效果 | 命名风格 |
---|---|
淡入/淡出 f | ade_in/fade_out |
从某个方向淡入/淡出 | fade_方向_in(out),右边淡入淡出fade_right_in(out) |
从某个方向弹入/弹出 | push_方向_in(out),右边推入推出push_right_in(out) |
从某个方向滑入/滑出 | slide_in(out)from方向,右边滑入滑出slide_in(out)_from_right |
-
strings和colors资源文件小驼峰命名法,命名风格大致如下:
- string命名格式:XX界面_XX功能_str,如 activity_home_welcome_str
- color命名格式:color_16进制颜色值,如红色 color_ff0000
- 像string通常建议把同一个界面的所有string都放到一起,方便查找。而color的命名则省去我们头疼的想这个颜色怎么命名。
- selecor、drawable、layer-list资源文件 小驼峰命名法。命名风格通常都是XX_selector、XX_drawable、XX_layer。
举两个比较常用的例子:
1. 按钮按压效果button_selector,正常状态命名为button_normal(XX_normal),按压状态命名为button_pressed(XX_pressed)
2. 选择效果checkbox_selector,未选中状态命名为checkbox_unchecked(XX_unchecked),选中状态为checkbox_checked(XX_checked)
-
styles、dimens资源文件
- style采用大驼峰命名法,主题可以命名为XXTheme,控件的风格可以命名为XXStyle
- dimen采用小驼峰命名法,如所有Activity的titlebar的高度,activity_title_height_dimen
-
控件id命名
控件 | 前缀缩写 |
---|---|
RelativeLayout | rl |
LinearLayout | ll |
FrameLayout | fl |
TextView | tv |
Button | btn |
ImageButton | imgBtn |
ImageView | imgView或iv |
CheckBox | chk |
RadioButton | rdoBtn |
analogClock | anaClk |
DigtalClock | dgtClk |
DatePicker | dtPk |
EditText | edtTxt或et |
TimePicker | tmPk |
toggleButton | tglBtn |
ProgressBar | proBar |
SeekBar | skBar |
AutoCompleteTextView | autoTxt |
ZoomControl | zmCtl |
VideoView | vdoVi |
WebView | webVi |
Spinner | spn |
Chronometer | cmt |
ScollView | sclVi |
TextSwitch | txtSwt |
ImageSwitch | imgSwt |
ListView | lv |
GridView | gv |
ExpandableList | epdLt |
MapView | mapVi |
2.3编码规范
2.3.1 import语句
- import不要使用通配符
- 不要换行
- 顺序和间距
import语句可分为以下几组,按照这个顺序,每组由一个空行分隔:
- 所有的静态导入独立成组
- com.google imports(仅当这个源文件是在com.google包下)
- 第三方的包。每个顶级包为一组,字典序。例如:android, com, junit, org, sun
- java imports5.javax imports组内不空行,按字典序排列。
2.3.2 要分门别类存放各种类
2.3.3 Layout中的常量要在strings.xml文件中定义
以下使用方式错误: <TextView android:text="评论">
2.3.4 Layout中所有空间字体大小,都定义在dimens.xml中
<resources>
<dimen name="bottom_tab_font_size">12dp</dimen>
<dimen name="bottom_tab_padding_up">5dp</dimen>
<dimen name="bottom_tab_padding_drawable">8dp</dimen>
</resources>
2.3.5 Activity中,onCreate()方法拆分为3个部分
- initVariables():初始化变量
- initViews();加载layout布局文件,初始化控价
- loadData():调用MobileAPI;
2.3.6 使用fastJSON自定义实体来作为MobileAPI的数据载体
2.3.7 页面之间传值,坚持使用Intent携带序列化实体数据的方式。禁止为了省事使用全局变量进行传值的方式
2.3.8 为空间添加事件,禁止在layout中直接声明事件的方法,以下代码不允许
<Button android:onclick="gotoLogin"..../>
2.3.9 为节省内存,请使用ArrayList<自定义实体>,而不是HashMap
2.3.10 图片的处理,请统一使用第三方组建ImageLoader或Fresco来进行异步加载
2.3.11 SharedPreferences仅用于简单的配置信息,例如设置页面的各种开关。对于复制的对象,还是要保存在本地文件中
2.3.12 Activity中不要嵌套内部类,尽量独立出来
2.3.13 Javadoc
格式 Javadoc块的基本格式如下所示:
/**
* Multiple lines of Javadoc text are written here,
* wrapped normally...
*/
public int method(String p1) { ... }
或者是以下单行形式:
/** An especially short bit of Javadoc. */
-
段落
- 空行(即,只包含最左侧星号的行)会出现在段落之间和Javadoc标记(@XXX)之前(如果有的话)。
- 除了第一个段落,每个段落第一个单词前都有标签,并且它和第一个单词间没有空格。
-
Javadoc标记
- 标准的Javadoc标记按以下顺序出现:@param, @return, @throws, @deprecated,
- 前面这4种标记如果出现,描述都不能为空。 当描述无法在一行中容纳,连续行需要至少再缩进4个空格。
-
摘要片段
- 每个类或成员的Javadoc以一个简短的摘要片段开始。这个片段是非常重要的,在某些情况下,它是唯一出现的文本,比如在类和方法索引中。
- 这只是一个小片段,可以是一个名词短语或动词短语,但不是一个完整的句子。它不会以A {@code Foo} is a…或This method returns…开头,它也不会是一个完整的祈使句,如Save the record…。然而,由于开头大写及被加了标点,它看起来就像是个完整的句子。
Tip: 一个常见的错误是把简单的Javadoc写成 /** @return the customer ID /,这是不正确的。它应该写成/* Returns the customer ID. */。
-
哪里需要使用Javadoc—— 至少在每个public类及它的每个public和protected成员处使用Javadoc,以下是一些例外:
- 例外:不言自明的方法
对于简单明显的方法如getFoo,Javadoc是可选的(即,是可以不写的)。这种情况下除了写”Returns the foo”,确实也没有什么值得写了。 单元测试类中的测试方法可能是不言自明的最常见例子了,我们通常可以从这些方法的描述性命名中知道它是干什么的,因此不需要额外的文档说明 Tip: 如果有一些相关信息是需要读者了解的,那么以上的例外不应作为忽视这些信息的理由。例如,对于方法名getCanonicalName,
- 例外:重载 如果一个方法重载了超类中的方法,那么Javadoc并非必需的。
- 可选的Javadoc: 对于包外不可见的类和方法,如有需要,也是要使用Javadoc的。如果一个注释是用来定义一个类,方法,字段的整体目的或行为,那么这个注释应该写成Javadoc,这样更统一更友好。
- 例外:不言自明的方法