开发规范
一、前言
1.1 为什么需要开发规范
编码规范对于程序员而言尤为重要，有以下几个原因：
- 一个软件的生命周期中，80%的花费在于维护
- 几乎没有任何一个软件，在其整个生命周期中，均由最初的开发人员来维护
- 编码规范可以改善软件的可读性，可以让程序员尽快而彻底地理解新的代码
- 如果你将源码作为产品发布，就需要确任它是否被很好的打包并且清晰无误，一如你已构建的其它任何产品
1.2 开发规范的作用
- 减少维护花费
- 提高可读性
- 加快工作交接
- 减少名字增生
- 降低缺陷引入的机会
二、命名规范
命名规范大体是已 java 的命名规范为基础进行的更改，如果这里没有说明就默认以 java 命名规范为准。
2.1 常量命名规范
2.1.1 说明
常量用于保存需要常驻内存中并且经常使用变化不多的数据，定义常量的名称的时候需要遵循望文知意的原则；
2.1.2 规则
- 全部为大写字母；
- 中间以“_”连接；
- 望文知意原则；
2.1.3 备注
代码中涉及到直接使用某个字符串或者其他基本类型的值时，建议定义成常量，避免多处直接使用同样的值作为参数。
2.1.4 举例
- 如：定义一个常量表示最小屏幕宽度的常量，则可以定义一个int类型的常量，该常量可以命名为：“MIN_SCREEN_WIDTH“；
- 其他举例：
- 例如：static final int MIN_SCREEN_WIDTH = 4；( √)
- 例如：static final int min_screen_width = 4;（×）
- 例如：static final int minScreenWidth = 4; （×）
- 例如：static final int WIDTH = 4；（×）
- 例如：static final int width = 4；（×）
- 例如：static final int wd = 4；（×）
2.2 变量命名规范
2.2.1 说明
变量用于保存系统中的临时数据，变量命名时遵循望文知意，简单明了，驼峰标示等原则。
2.2.2 规则
- 首字母小写；
- java驼峰命名；
- 望文知意原则；
- 推荐引用类型变量添加前缀“m”；
- boolean类型变量添加前缀“is”；
- 如果是View组件变量，则组件名称为xml文件中定义的ID名称去掉下划线，下划线后一位大写；
2.2.3 举例
- 如：定义一个表示最小屏幕宽度的变量，则可以定义一个int型的临时变量为：mMinScreenWidth；
- 例如：static final int mMinScreenWidth = 4； ( √)
- 例如：static final int minWidth = 4；（×）
- 例如：static final int screenWidth = 4；（×）
- 例如：static final int width = 4；（×）
- 例如：static final int min = 4； （×）
- 例如：static final int msw = 4； （×）
2.3 方法名命名规范
2.3.1 说明
方法名的命名应该遵循简单明了的原则；
2.3.2 规则
- 首字母小写；
- java驼峰命名；
- 简单明了原则；
- 初始化方法init*（每个init做一件事）
2.3.3 备注
- 同时在方法的实现上，尽量不要在一个方法中出现太多实现代码，如一个方法有几百行的实现逻辑，推荐在逻辑复杂时，按功能点拆分出多个方法，便于阅读。
- 另外，出现功能一样的实现逻辑，尽量抽取公用方法，避免将实现逻辑复制到多个用到的地方。
2.3.4 举例
- 如：定义一个获取屏幕宽度的方法，依照上述原则，则可以定义为一个静态方法：public static int getScreenWidth();
- 例如：public static int getScreenWidth();( √)
- 例如：public static int getscreenwidth();（×）
- 例如：public static int getScreenwidth();（×）
- 例如：public static int getWidth();（×）
- 例如：public static int getScreen();（×）
- 例如：public static int getSW();（×）
2.4 类命名规范
2.4.1 说明
类名主要表示一个类的作用，需要简明扼要，望文知意，并且首字母大写。
2.4.2 规则
- 首字母大写；
- java驼峰命名；
- 望文知意原则；
- 能够说明类的功能和主要作用（注释的作用）；
- Acitivity类以Acitivity结尾；
- Fragment类以Fragment结尾；
- Service类以Service结尾；
- BroadcastReceiver类以Receiver结尾；
- ContentProvider类以Provider结尾；
- Application类以Application结尾（或直接APP命名）；
- 自定义View类以Custom**View结尾；
- 自定义Adapter类以Adapter结尾；
- adapter中的ViewHolder以Holder结尾；
- 实体Bean以Model或Bean结尾；
- 工具类以Utils结尾
2.4.3 举例
- 如：定义一个获取屏幕信息的工具类，则可以定义为public class ScreenUtils；
- 例如：public class ScreenUtils; ( √)
- 例如：public class Screenutils; （×）
- 例如：public class Screen; （×）
- 例如：public class screenutils; （×）
- 例如：public class screen; （×）
- 例如：public class su；（x）
2.5 接口命名规范
2.5.1 说明
接口命名需要简单明了，长度不宜过长；
2.5.2 规则
- 首字母大写（第二个字母也是大写）；
- java驼峰命名；
- 望文知意原则；
- 建议在名称前面追加“I”；
2.5.3 备注
- I**Listener
- I**CallBack
- I**；
2.5.4 举例
- 如：定义一个activity的方法接口，实现接口中的某些方法：public
interface IFunctionListener； - 例如：public interface IFunctionListener；( √)
- 例如：public interface BaseActivity; （×）
- 例如：public interface Baseactivityinter; （×）
- 例如：public interface BaseInter; （×）
- 例如：public interface ActivityInter；（×）
2.6 包名规范
2.6.1 说明
用于分类管理类文件；
2.6.2 规则
- 所有字母小写；
- 简单明了，层级很深，没有拼接的包名；
- 望文知意；
- 按功能划分包名，如“我的”
- 工具类可以划分为一个工具类的包名，utils，里面可以添加包名层级；
- 系统类的可以划分为一个系统类的包，system，里面可以添加包名层级；
- 组件类的可以划分为一个组件类的包，*，里面添加adapter的包名，自定义view包名；
- Service类的可以划分为一个服务类的包，service，里面可以添加包名层级；
- 数据库相关类可以划分为一个数据库类，db，里面可以添加数据库相关类，Bean类，数据库服务类等；
- 广播类的可以划分为广播类的包，receiver，可以放一些广播相关的类；
- 网络类相关的可以划分为，network，放一些网络相关的类；
- Fragment类存放在fragment包下；
- Activity类存放在Activity包下；
- 在接口过多的情况下可以单独为接口划分一个包interface或infa
2.7 目录名称规范
2.7.1 说明
主要是一些jar包，so文件的配置目录名称；
2.7.2 规则
- 全部为小写字母；
- 简单明了；
- 望文知意；
- 驼峰表示；
2.7.3 举例
- 后期增加目录的可能性不多，现列举出系统中存在的目录结构：
- lib：第三方jar的保存路径；
- jniLibs：jni引用的so文件的目录；
2.8 布局文件名称规范
2.8.1 说明
主要包含资源文件的命名问题；
2.8.2 规则
- 全部为小写字母；
- 中间以”_”连接；
- 望文知意原则；
- 布局文件的开头问类名；
- 列表项的xml布局文件名称：类名_item.xml；
- activity类的xml文件名称：类名_activity.xml；
- fragment类的xml文件名称：类名_fragment.xml；
- 自定义View的xml文件的名称：类名_父类名.xml；
2.8.3 列举
- 如：如定义H5Activity的xml文件名称，则可以定义为h5.xml；尽量不使用大写字母等。
2.9 drawable文件名称规范
2.9.1 说明
drawable文件名称命名规范；
2.9.2 规则
- 全部为小写字母；
- 中间以”_”连接；
- 望文知意原则；
- 布局文件的开头问类名；
- 11_22_33_44；44：selector，shape（大概五六个，暂时不定义其他的）； 33：src、bg、color（可扩展，可为空）； 22：状态名称或者为空；11：业务名称
2.9.3 举例
* 如：比如一个textview组件，可点击用于支付的按钮，则可以把ID定义为： tv_pay_money；
2.10 资源ID规范
2.9.1 说明
各种资源ID的定义问题；
2.9.2 规则
- 全部为小写字母；
- 中间以”_”连接；
- 望文知意原则；
2.9.3 备注
- 可以考虑按照组件的名称的缩写作为前缀，（同一个xml文件中ID名称不能重复）如：组件简写（大写字母缩写）_业务名称
- TextView的组件:tv_pay_money
- Button的组件：btn_pay_money
- EditText的组件：et_user_name
- LinerLayout组件：ll_container
2.9.4 举例
* 如：比如一个textview组件，可点击用于支付的按钮，则可以把ID定义为： tv_pay_money；
三、注释规范
3.1 类注释
成员变量和常量需要使用如下注释的形式，注释位于变量的上侧；
/**
*
**/
3.2 内部逻辑注释
内部逻辑注释模板：
//支付成功
if (response.getRet() == 0) {
Toast.makeText(H5Activity.this, "支付成功", Toast.LENGTH_LONG).show();
goToNext(response);
}
//支付失败
else if (response.getRet() == -1) {
Toast.makeText(H5Activity.this, "支付失败", Toast.LENGTH_LONG).show();
//刷新当前页面
reflush(currentUrl);
}
四、代码顺序
在一个典型的Activity中代码的顺序如下：
/**
* author:sh
* desc:该class的作用
* time:yyyy-MM-dd
**/
public class ClassName {
//（1） 成员变量集合
//（2） 回调方法集合
若该类为activity，则：onCreate、**、onDestory；
若该类为Fragment、则：onCreateView、**、onDestory；
//（3） 其他方法集合
}
五、代码风格
5.1 大括号换行
左大括号不换行，右大括号换行；
class MyClass {
int func() {
if (something) {
// ...
} else if (somethingElse) {
// ...
} else {
// ...
}
}
}
5.2 小括号空格
if (condition) {
body();
} // 推荐
5.3 缩进
- 4 个空格作为缩进排版的一个单位，不使用制表符 tab。
- 8 个空格作为换行后的缩进，包括函数调用和赋值。
- Instrument i = someLongexpression_r(that, NotFit, on, one, line); // 推荐
5.4 每一行的长度
- 尽量避免一行的长度超过 100 个字符。（如果屏幕比例较大时可以适当增加）
- 例外：如果注释行包含了超过 100 个字符的命令示例或者 url 文字，为了便于剪切和复制，其长度可以超过 100 个字符。
- 例外：import 行可以超过限制，因为很少有人会去阅读它。这也简化了编程工具的写入操作。
5.5 每次声明一个变量
- 推荐一行一个声明，因为这样以利于写注释；
- int level; // indentation level
- int size; // size of table
5.6 if-else语句
if-else语句应该具有如下格式：
if (condition) {
statements;
}
if (condition) {
statements;
} else {
statements;
}
if (condition) {
statements;
} else if (condition) {
statements;
} else{
statements;
}
注意：if语句总是用”{“和”}“括起来，避免使用如下容易引起错误的格式：
if (condition) // 避免
statement;
5.7 for语句
一个for语句应该具有如下格式：
for (initialization; condition; update) {
statements;
}
当在for语句的初始化或更新子句中使用逗号时，避免因使用三个以上变量，而导致复杂度提高。
若需要，可以在for循环之前(为初始化子句)或for循环末尾(为更新子句）使用单独的语句。
5.8 while语句
一个while语句应该具有如下格式：
while (condition) {
statements;
}
5.9 do-while语句
do {
statements;
} while (condition);
5.10 switch语句
一个switch语句应该具有如下格式：
switch (condition) {
case ABC:
statements;
/* falls through */
case DEF:
statements;
break;
case XYZ:
statements;
break;
default:
statements;
break;
}
每当一个case顺着往下执行时（因为没有break语句），通常应在break语句的位置添加注释。
六、异常规范
6.1 异常名称
定义异常的时候，异常的后缀名称以Exception结尾，及**Exception；
6.2 异常描述
尽量英文描述，简单明了；
6.3 异常格式
一个try-catch语句应该具有如下格式：
try {
statements;
} catch (ExceptionClass e) {
statements;
}
try {
statements;
} catch (ExceptionClass e) {
statements;
} finally {
statements;
}
七、其他规范
7.1 源文件的函数小于2K
一般来说源文件的行数不能大于2K行，过多的话可以考虑拆分功能，拆分函数等；
7.2 使用TODO注释
对那些临时性的、短期的、够棒但不完美的代码，请使用 TODO 注释。
TODO 注释应该包含全部大写的 TODO，后跟一个冒号：
// TODO: Remove this code after the UrlTable2 has been checked in.
// TODO: Change this to use a flag instead of a constant.
如果 TODO 注释是“将来要做某事”的格式）。
7.3 使用自定义LOG
在系统中需要打印LOG的时候，尽量使用自定义的LOG，自定义的LOG在开发环境的时候会打印日志，正式环境的时候不会打印日志。
7.4 使用自定义TAG
在系统打印LOG的时候，使用TAG尽量使用tab，同意的TAG标志。
作者： Beetle_sxy
时间： 2017/8/10
