Android发编码及文档规范

开发编码及文档规范 3TI Solutions All rights reserved 1 43 编码及文档规范 AndroidAndroid 作 者 韩瑜 创建日期 2015 11 16 更新日期 2015 11 18 文档编号 当前版本 1 0 开发编码及文档规范 3TI Solutions All rights reserved 2 43 版本控制版本控制 变更记录变更记录 操作 创建 新增 修改 发布 删除 操作 创建 新增 修改 发布 删除 版版 本本 日期日期操作操作作者作者变更说明变更说明 V 0 1 2015 11 18 创建韩瑜 V 0 2 审阅审阅 姓名姓名职位职位 分发分发 拷贝编号拷贝编号姓名姓名位置位置 岗位岗位 1 2 3 4 开发编码及文档规范 3TI Solutions All rights reserved 3 43 目 录 1编写目的编写目的 4 2适用范围适用范围 4 3编码规范编码规范 4 3 1编码 4 3 2基本格式 4 3 3对齐 6 3 4空行空格 7 3 5断行 9 3 6注释 12 3 7命名规则 16 3 8声明 21 3 9表达式与语句 22 4类接口与类接口与 ANDROID 25 4 1类和接口 25 4 2XML文件书写规范 27 4 3编码规范 31 开发编码及文档规范 3TI Solutions All rights reserved 4 43 1编写目的编写目的 本规范由编程原则组成 融合并提炼了 Android 开发人员长时间积累下来的成熟经验 意在帮助形成良好一致的编程风格 以达到事半功倍的效果 2适用范围适用范围 适用于 Android 开发的应用 3编码规范编码规范 3 13 1编码 Android 代码必须只使用 UTF 8 编码格式 3 23 2基本格式 3 2 1 源代码文件 java 的布局顺序是 包 import 语句 类 正例正例 packagecom sunsharp importjava awt peer CanvasPeer import java io public class ClassName 开发编码及文档规范 3TI Solutions All rights reserved 5 43 3 2 2 遵循统一的布局顺序来书写 import 语句 不同类别的 import 语句之间用空行分隔 说明 说明 package 语句其后可跟 import 语句 而且与 package 间隔一个空行 import 包的排列 顺序为 java 开头的包在最前面 接下来是引自外部的包 再接下来是应用程序自身 的包 即 import 中标准的包名要在本地的包名之前 而且按照字母顺序排列 正例正例 packagecom sunsharp import java util ArrayList java 自身的包 importjava util List importorg apache http 第三方的包 mon 程序自身的包 3 2 3 if else else if for while do switch 等语句独占一行 执行语句不得紧跟其后 不 论执行语句有多少都要加 这样可以防止书写失误 也易于阅读 正例 正例 if varible1 varible2 varible1 varible2 反例 反例 开发编码及文档规范 3TI Solutions All rights reserved 6 43 下面的代码执行语句紧跟 if 的条件之后 而且没有加 违反规则 if varible1 varible2 varible1 varible2 说明 说明 这样便于程序阅读和查找 正例正例 length 10 width 5 矩形的长与宽关系较密切 放在一起 strCaption Test 反例反例 length 10 strCaption Test width 5 3 33 3对齐 3 3 1 一般禁止使用制表符 必须使用空格进行缩排 缩进为 4 个空格 说明 说明 对于利用 Eclipse 等编程工具的 可以设置 TAB 键为 4 个空格代替 消除不同编辑 器对制表符处理的差异 3 3 2 程序的分界符 和 应独占一行 同时与引用它们的语句左对齐 之内的代码 块使用缩进规则对齐 说明 说明 这样使代码便于阅读 并且方便注释 建议 1 1 1 源程序中关系较为紧密的代码应尽可能相邻 开发编码及文档规范 3TI Solutions All rights reserved 7 43 do while 语句可以例外 while 条件可与 在同一行 正例 正例 voidfunction intvar while condition doSomething 与 缩进 4 格 与引用它们的模块左对齐 反例 反例 voidfunction intvar while condition doSomething 3 3 3 多维的数组如果在定义时初始化 按照数组的矩阵结构分行书写 正例正例 int number 1 1 1 2 4 8 3 9 27 4 16 64 3 3 4 相关的赋值语句等号对齐 开发编码及文档规范 3TI Solutions All rights reserved 8 43 正例正例 width 50 length 20 height 40 3 不同逻辑程序块之间要使用空行分隔 空行起着分隔程序段落的作用 适当的空行可以使程序的布局更加清晰 下列情况应该总是使用空行 一个源文件的两个片段 section 之间 类声明和接口声明之间 常量声明区域之后 方法声明之前 方法内的局部变量和方法的第一条语句之间 一个方法内的两个逻辑段之间 用以提高可读性 3 43 4空行空格 3 4 1 不同逻辑程序块之间要使用空行分隔 说明 说明 空行起着分隔程序段落的作用 适当的空行可以使程序的布局更加清晰 下列情况应该总是使用空行 一个源文件的两个片段 section 之间 类声明和接口声明之间 开发编码及文档规范 3TI Solutions All rights reserved 9 43 常量声明区域之后 方法声明之前 方法内的局部变量和方法的第一条语句之间 一个方法内的两个逻辑段之间 用以提高可读性 正例正例 voiddoSomething Connection con null 数据库连接 booleanreturnParameter false 返回 空一行 if代码的注释 if reconsign null return false 反例 反例 voiddoSomething Connection con null 数据库连接 booleanreturnParameter false 返回 if代码的注释 开发编码及文档规范 3TI Solutions All rights reserved 10 43 if reconsign null return false 3 4 2 一元操作符如 类型 等前后不加空格 这类操作符 前后不加空格 正例正例 value value count number i 5 box getWidth 3 4 3 多元运算符和它们的操作数之间至少需要一个空格 说明 说明 空格的多少根据上下文调整 正例正例 value oldValue total value number 2 3 4 5 方法名之后不要留空格 说明 说明 方法名后紧跟左括号 3 4 6 向后紧跟 向前紧跟 紧跟处不留空格 之后要留空格 不是行结 束符号时其后要留空格 正例 正例 开发编码及文档规范 3TI Solutions All rights reserved 11 43 例子中的凵凵代表空格 for i 凵凵 凵凵 0 凵凵 i 凵凵 或 EPSINON case SPAN OFF 处理语句 break default 处理语句 break 开发编码及文档规范 3TI Solutions All rights reserved 31 43 3 9 6 避免在 if 条件中赋值 说明 Java 编译器对 boolean 型变量在 if 条件语句中的赋值时合法的 对整型变量的赋 值是不合法的 3 9 7 带值的返回语句不需要用括号 说明 除非有时不得不用括号使返回结构更加明显 正例 return return myDisk size return size size defaultSize 用括号使返回结构更加明显 3 9 8 循环嵌套次数不大于 3 次 3 9 9 do while 语句和 while 语句仅使用一个条件 说明 保持程序简洁 如果需要判断的条件较多 建议用临时布尔变量先计算是否满足条 件 正例 Boolean bCondition do bCondition tAp iPortNo bStateAcpActivity PASSIVE tAp iPortNo bStateLacpActivity PASSIVE 3 9 10 在多重循环中 如果有可能 应当将最长的循环放在最内层 最短的循环放在最外 层 以减少 CPU 跨切循环层的次数 正例 for iCol 0 iCol 5 iCol for iRow 0 iRow 100 iRow 开发编码及文档规范 3TI Solutions All rights reserved 32 43 iSum iSum aiDate iRow iCol 反例 for iRow 0 iRow 100 iRow for iCol 0 iCol 5 iCol iSum iSum aiDate iRow iCol 4类类接口与接口与 android 4 1 类类 4 1 1 类内部的代码布局顺序 类变量 属性 构造函数 方法 正例 class Test private int exampleVar public string name public Test 开发编码及文档规范 3TI Solutions All rights reserved 33 43 public void setName string name private void method 4 1 2 功能相关的方法放在一起 说明 如接口中关系较紧密的的几个方法 类属性的 get 和 set 方法 有调用关系的方法 重载的方法等有相近或相关的方法尽可能放在一起 方便阅读 正例 正例 class Sample extends Object int ivar1 int ivar2 String name Sample inti int j ivar1 i ivar2 j public void setName String name this name name 开发编码及文档规范 3TI Solutions All rights reserved 34 43 public String getName returnthis name int method1 method2 void method2 4 1 3 函数的参数个数不宜超过 4 个 说明 过多的函数参数会导致性能降低 4 14 使程序结构体现程序的目的 正例 return booleanExpression 反例 if booleanExpression return true else return false 开发编码及文档规范 3TI Solutions All rights reserved 35 43 4 15保证内部类定义成private 提高类的封装性 4 16嵌套内部类不能超过两层 4 17一个接口可以有多个实现类 实现类共同的变量在接口里声明 4 24 2 xmlxml 文件书写规范文件书写规范 Android 下的开发基本可沿用 Java 下的编码规范 这里只是一些命令规范和日志的使用做 一些补充 4 21 res layout 下的 xml 文件统一用小写和下划线 组合命名 并加上前缀以便区分 正例 对话框的 xml 配置文件 dlg name xml 4 2 2ayout 中的 id 采用以下命名模式 view 缩写 模块名称 view 的逻辑名称 说明 view 的缩写详情如下 ayoutView lv RelativeView rv TextView tv Button btn ImageButton imgBtn ImageView mgView 或则 iv CheckBox chk RadioButton rdoBtn analogClock anaClk DigtalClock dgtClk DatePicker dtPk 开发编码及文档规范 3TI Solutions All rights reserved 36 43 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 正例 id lv appstore applist 反例 id ListView01 4 2 3activity 文中的 view 变量采用以下命名模式 逻辑名称 view 缩写 activity 文中的 view 变量采用以下命名模式 逻辑名称 view 缩写 正例 开发编码及文档规范 3TI Solutions All rights reserved 37 43 ListView applistLv 4 2 4 res drawable 下的资源文件采用以下命名模式 activity 名称 逻辑名称 common 逻辑名称 正例 main default png main pressed png 4 25 strings xml 中的 id 采用以下命名模式 activity 名称 功能模块名称 逻辑名称 activity 名称 逻辑名称 common 逻辑名称 正例 正在下载 4 2 6 字符串信息应统一在 strings xml 中定义 调试信息除外 4 2 7 使用日志时 不重要的信息定义在 debug 等级或者 info 等级 较为严重的情况把日 志定义的 warn 等级和 error 等级 正常情况下尽量不使用 System out println 作为日 志的输出 4 2 8 使用日志时 统一在类的声明后面加上 Private static finnal String TAG 类名 输出日志的时候使用 Log e TAG content 进行输出 4 2 9 资源布局文件 XML 文件 layout 布局文件 全部小写 采用下划线命名法 1 contentview 命名 Activity 默认布局 以去掉后缀的 Activity 类进行命名 不加后 缀 开发编码及文档规范 3TI Solutions All rights reserved 38 43 功能模块 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 4 2 10 资源布局文件 XML 文件 layout 布局文件 前面为动画的类型 后面为方向 动画命名例子 规范写法备注 fade in 淡入 fade out 淡出 push down in 从下方推入 开发编码及文档规范 3TI Solutions All rights reserved 39 43 push down out 从下方推出 push left 推像左方 slide in from top 从头部滑动进入 zoom enter 变形进入 slide in 滑动进入 shrink to middle 中间缩小 4 2 11 资源文件 图片 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 功能 说明 命名后缀 开发编码及文档规范 3TI Solutions All rights reserved 40 43 4 3 编码规范 7 java 代码中不出现中文 最多注释中可以出现中文 8 activity 中的 view 变量命名命名模式为 逻辑名称 view 缩写建议 如果 layout 文件很复杂 建议将 layout 分成多个模块 每个模块定义一个 moduleViewHolder 其成员变量包含所属 view 9 strings xml 中的 id 命名命名模式 activity 名称 功能模块名称 逻辑名称 activity 名称 逻辑名称 common 逻辑名称 strings xml 中 使用 activity 名称 注释 将文件内容区分开来 drawable 中的图片命名命名模式 activity 名称 逻 辑名称 common 逻辑名称 10 styles xml 将 layout 中不断重现的 style 提炼出通用的 style 通用组件 放到 styles xml 中 11 图片尽量分拆成多个可重用的图片 后缀说明 unit 在使用 xml 的 tilemode 来配图片时 element 图片使用此后缀 nor 图片的状态 代表普通状态 hl 图片的状态 代表高亮状态 press 图片的状态 代表按下状态 select 图片的状态 代表其所占的 view 被选中 unselect 图片的状态 代表其所占的 view 没有被选中 开发编码及文档规范 3TI Solutions All rights reserved 41 43 12 引用第三方库要慎重 避免应用大容量的第三方库 导致客户端包非常大 13 使用静态变量方式实现界面间共享要慎重 14 Log 系统名称 模块名称 接口名称 详细描述 15 不要重用父类的 handler 对应一个类的 handler 也不应该让其子类用到 否则会 导致 message what 冲突 16 activity 中在一个 View OnClickListener 中处理所有的逻辑 17 strings xml 中使用 1 s 实现字符串的通配 18 如果多个 Activity 中包含共同的 UI 处理 那么可以提炼一个 CommonActivity 把通用部分叫由它来处理 其他 activity 只要继承它即可 19 使用 button activitgroup 实现 tab 效果时 使用 Button setSelected true 确保按钮处于选择状态 并使 activitygroup 的当前 activity 与该 button 对应 20 如果所开发的为通用组件 为避免冲突 将 drawable layout menu values 目录 下的文件名增加前缀 21 数据一定要效验 例如字符型转数字型 如果转换失败一定要有缺省值 服务端 响应数据是否有效判断 22 23 Android 性能优化 24 1 http 用 gzip 压缩 设置连接超时时间和响应超时时间 http 请求按照业务需求 分为是否可以缓存和不可缓存 那么在无网络的环境中 仍然通过缓存的 httpresponse 浏览部分数据 实现离线阅读 25 2 listview 性能优化 1 复用 convertView 在 getItemView 中 判断 convertView 是否为空 如果不为空 可复用 如果 couvertview 中的 view 需要 开发编码及文档规范 3TI Solutions All rights reserved 42 43 添加 listerner 代码一定要在 if convertView null 之外 2 异步加载图 片 item 中如果包含有 webimage 那么最好异步加载 3 快速滑动时不显示图片当 快速滑动列表时 SCROLL STATE FLING item 中的图片或获取需要消耗资源的 view 可以不显示出来 而处于其他两种状态 SCROLL STATE IDLE 和 SCROLL STATE TOUCH SCROLL 则将那些 view 显示出来 26 3 使用线程池 分为核心线程池和普通线程池 下载图片等耗时任务放置在普通 线程池 避免耗时任务阻塞线程池后 导致所有异步任务都必须等待 27 4 异步任务 分为核心任务和普通任务 只有核心任务中出现的系统级错误才会 报错 异步任务的 ui 操作需要判断