代码规范
/** TAG */
private final String TAG = getClass().getSimpleName();
/** 是否为编码规范 */
private boolean m_bIsCoding = true;
/** 标题 */
private TextView m_txtTitle = null;
/** 编码规范 */
private WebView m_webCoding = null;
/** 示例代码 */
private WebView m_webSample = null;
/** 切换 */
private Button m_btnSwitch = null;
public class SampleCode
{
/** 圆周率 */
public static final double PI = 3.1415926535897932384626433832795;
/** 整型值 */
private int m_nValue = 0;
/** 字符值 */
private char m_cValue = '0';
/** 浮点值 */
private float m_fValue = 0.0f;
/** 双精度值 */
private double m_dValue = 0.0;
/** 布尔值 */
private boolean m_bValue = true;
/** 字符串值 */
private String m_strValue = "";
/** 是否为 16 进制 */
protected boolean m_bHex = false;
/**
* 获取整型值
* @return
*/
public int getNValue()
{
return m_nValue;
}
/**
* 获取字符串值
* @return
*/
public String getStrValue()
{
return m_strValue;
}
/**
* 设置整型值
* @param n
*/
public void setNValue(final int n)
{
m_nValue = n;
}
/**
* 设置字符串值
* @param str
*/
public void setStrValue(final String str)
{
if (str == null) return;
m_strValue = str;
}
/**
* 是否为 16 进制
* @return
*/
public boolean isHex()
{
return m_bHex;
}
/**
* 构造函数
* @param n 整型值
*/
public SampleCode(final int n)
{
// 整型值
m_nValue = n;
}
/**
* 加法
* @param n 整数
*/
private void add(final int n)
{
m_nValue += n;
}
/**
* 加法
* @param n1 整数 1
* @param n2 整数 2
* @return 结果
*/
public int add(final int n1, final int n2)
{
return n1 + n2;
}
/**
* 加法
* @param n 整数
* @param ns 整数数组
* @return 是否相加成功
*/
public boolean add(final int n, final int[] ns)
{
try
{
if (n < 1 || n > ns.length)
{
return false;
}
m_nValue = 0;
for (int i = 0; i < n; i++)
{
// 加法
add(ns[i]);
}
}
catch (Exception e)
{
e.printStackTrace();
return false;
}
return true;
}
}package cn.tbtech.codingruler;
/**
* 类的基本描述写在这里...
*
*
1. 代码
*
* - 1.1. 请使用 UTF-8 格式来编写代码, 避免出现中文乱码
*
- 1.2. 代码缩进必须使用 Tab, 而不能使用空格, 且代码布局尽量对齐
*
- 1.3. 代码中不允许出现警告(Java 代码中无法消除的警告要用 @SuppressWarnings)
*
- 1.4. 去掉无用的包(命名空间), 方法(函数), 变量(字段)等, 减少僵尸代码
*
- 1.5. 在 Eclipse 中使用 Lint 工具来查看并消除警告和错误
*
- 1.6. 在 Eclipse 中使用 Ctrl+Shift+F 来格式化代码, 然后再进行调整
*
- 1.7. 在 Eclipse 中使用 Ctrl+Shift+O 来格式化 import 包
*
*
* 2. 命名规则
* 2.1. 基本原则
*
* - 2.1.1. 变量, 方法, 类和接口等, 其命名要表义, 不能使用 name1, name2 等无直接意义的命名
*
- 2.1.2. 命名不能太长, 适当使用简写或缩写, 如 nMaximumNumber 简写为 nMaxNum
*
- 2.1.3. 方法名以小写字母开始, 其后每个单词首字母大写(即使用驼峰表示法), 如 doSomething
*
- 2.1.4. 方法名避免使用相似或者仅在大小写上有区别的名字
*
- 2.1.5. 方法名避免使用数字, 但可用 2 代替 to, 用 4 代替 for 等, 如 str2int
*
*
* 2.2. 类, 接口
*
* - 2.2.1. 所有单词首字母都大写, 使用能确切表示该类, 接口含义, 功能等的词, 一般采用名词
*
- 2.2.2. 接口带 I 或 On 等前缀, 或 Listener 等后缀, 如 OnClickListener
*
*
* 2.3. 常量, 变量
*
* - 2.3.1. 常量全部大写, 在单词与单词之间用下划线连接, 如 MAX_NUMBER
*
- 2.3.2. 变量前使用前缀 m_ 标识为成员变量, 如果是静态成员变量则为 ms_, 如 m_strUserName, ms_instance
*
- 2.3.3. 普通变量使用前缀 n, f, d, b, bt, str 等标识变量的数据类型, 如 nNum, strName
*
- 2.3.4. 某些局部变量可以根据实际情况灵活变通, 比如用于循环中的 i, j, k 等变量
*
- 2.3.5. 代码中禁止使用硬编码, 应把一些数字或字符串定义成常用量, 如圆周率等
*
- 2.3.6. 对于废弃不用的函数, 为了保持兼容性, 通常添加 @Deprecated, 如 {@link #doSomething()}
*
*
* 3. 注释
* 请参考 {@link #SampleCode} 类的注释
*
* - 3.1. 所有的注释, 不分编程语言(C, C++, Java, Objective-C 等), 均采用 Javadoc 格式
*
- 3.2. 在代码的关键函数部分, 逻辑处理部分, 复杂算法部分等, 必须添加注释
*
- 3.3. 代码中的注释尽量做到"宁多勿少", 必要的时候还必须配套相应的说明文档
*
- 3.4. 常量注释, 参见 {@link #PUB_VAR}
*
- 3.5. 变量注释, 参见 {@link #m_object0}
*
- 3.6. 函数注释, 参见 {@link #doSomething(boolean, double, String)}
*
- 3.7. 注释语言, 根据项目的要求来决定应该使用中文还是英文, 对于容易产生歧义的注释推荐使用英文
*
- 3.8. 标点符号, 如果使用中文进行注释, 为了保持对齐应该使用英文标点符号
*
*
* 4. Class 内部顺序和逻辑
*
* - 4.1. 每个 class 都应该按照一定的逻辑结构来排列成员变量, 方法, 内部类等, 从而达到良好的可读性
*
- 4.2. 总体上来说, 要按照先 private, 然后 protected, 最后 public, 先常量后变量
*
- 4.3. 函数的排布也应该有一个逻辑的先后顺序, 由轻到重, 或按照调用关系的先后顺序排列
*
- 4.4. 以下顺序可供参考:
* 定义 TAG, 一般为 private(可选)
* 定义 private 常量
* 定义 protected 常量
* 定义 public 常量
* 定义 private 变量
* 定义 protected 变量
* 定义 public get 方法
* 定义 public set 方法
* 定义 class 的构造方法
* 定义 private 方法
* 定义 protected 方法
* 定义 public 方法
* 定义 private 内部类, 参见 {@link #CodingRulerInternal}
*
*
* 5. 表达式与语句
* 5.1. 基本原则: 采用紧凑型风格来编写代码
* 5.2. 细则
*
* - 5.2.1. 条件表示式, 参见 {@link #conditionFun()}
*
- 5.2.2. switch 语句, 参见 {@link #switchFun()}
*
- 5.2.3. 循环语句, 参见 {@link #circulationFun()}
*
- 5.2.4. 错误与异常, 参见 {@link #exceptionFun()}
*
- 5.2.5. 其它, 参见 {@link #doSomething(boolean, double, String)}
*
*/
@SuppressWarnings("unused")
public class CodingRuler
{
/** TAG */
private final String TAG = getClass().getSimpleName();
/** 私有常量 MSG_NONE 的注释(同类型的常量可以分块并紧凑定义) */
private static final int MSG_NONE = 0; // 注意初始化值 0, 1, 2 的对齐
/** 私有常量 MSG_SUCCESS 的注释 */
private static final int MSG_SUCCESS = 1; // 运算符(+ - * / = | & 等)两端必须有空格
/** 私有常量 MSG_FAILED 的注释 */
private static final int MSG_FAILED = 2;
/** 保护常量的注释 */
protected static final String PRO_VAR = "protected";
/** 公有常量的注释 */
public static final String PUB_VAR = "public";
/** 私有成员变量 m_object0 的注释(同类型的成员变量可以分块并紧凑定义) */
private Object m_object0 = null;
/** 私有成员变量 m_object1 的注释 */
private Object m_object1 = null;
/** 私有成员变量 m_object2 的注释 */
private Object m_object2 = null;
/** 保护成员变量的注释 */
protected Object m_object3 = null;
/**
* 对于注释多于一行的, 采用这种方式
* 定义该变量
*/
protected Object m_object4 = null;
/**
* get 方法描述...
* @return
*/
public Object getObject0()
{
return m_object0;
}
/**
* set 方法描述...
*
* 1. 如果是 get 或 set 函数, 函数体可以只有一行, 且可以不用写参数说明和返回值说明
* 2. 如果变量为 boolean(布尔) 型, 则 get 函数一般写为 is 前缀, 如 m_bHex 变量的函数写为 isHex()
* 3. 除了数组初始化之外, 其余用到花括号"{}"的, 必须另起一行
* 4. 比如不能使用类似 if (bClose) { 这样的代码行, 必须把 { 另起一行
* @param obj
*/
public void setObject0(Object obj)
{
m_object0 = obj;
}
/**
* 构造方法
*/
public CodingRuler()
{
// ...
}
/**
* if 条件表达式原则
* 1. 通常 if 语句必须用花括号"{}"包括起来, 如果只有一句, 且为简单赋值或返回等, 可以使用不带 {} 的语句
* 2. 在含有多种运算符的表达式中, 使用圆括号来避免运算符优先级问题
* 3. 当判断条件很多时, 请将其它条件换行
*/
private void conditionFun()
{
boolean bCondition1 = true;
boolean bCondition2 = false;
boolean bCondition3 = false;
boolean bCondition4 = false;
boolean bCondition5 = false;
boolean bCondition6 = false;
if (bCondition1)
{
// Implementation...
}
if (bCondition1)
{
// Implementation...
}
else
{
// Implementation...
}
if (bCondition1)
{
// Implementation...
}
else if (bCondition2)
{
// Implementation...
}
else
{
// Implementation...
}
// 使用不带 {} 的语句
if (bCondition1) bCondition3 = true;
// 使用不带 {} 的语句
if (!bCondition2) return; // 注意, 非运算符 ! 的两端不需要空格
if ((bCondition1 == bCondition2) || (bCondition3 == bCondition4) || (bCondition5 == bCondition6))
{
}
}
/**
* switch 语句原则
* 1. switch 语句中, break 与下一条 case 之间, 空一行
* 2. 对于不需要 break 语句的, 请相连使用
* 3. 请默认写上 default 语句, 保持完整性
* 4. 在每一个 case 语句上写注释
*/
private void switchFun()
{
int nMsg = MSG_NONE;
switch (nMsg)
{
// 无
// 失败
case MSG_NONE:
case MSG_FAILED:
break;
// 成功
case MSG_SUCCESS:
break;
default:
break;
}
}
/**
* 循环表达式原则
* 1. 尽量使用 for each 语句代替原始的 for 语句
* 2. 循环中必须有终止循环的条件或语句, 避免死循环
* 3. 循环要尽可能的短, 把长循环的内容抽取到方法中去
* 4. 嵌套层数不应超过 3 层, 要让循环清晰可读
* 5. for 之后的花括号"{}"必须另起一行, while, do-while 等与之类似
*/
private void circulationFun()
{
// 除了数组初始化之外, 其余用到花括号"{}"的, 必须另起一行
int nArray[] = { 1, 2, 3, 4, 5 };
for (int nData : nArray)
{
// Implementation...
}
int nLength = nArray.length;
for (int i = 0; i < nLength; i++)
{
// Implementation...
}
boolean bCondition = true;
while (bCondition)
{
// Implementation...
}
do
{
// Implementation...
}
while (bCondition);
}
/**
* 异常捕获原则
* 1. 捕捉异常是为了处理它, 通常在异常 catch 块中输出异常信息
* 2. 资源释放的工作, 可以放到 finally 块部分去做, 如关闭 OutputStream 等
* 3. 一般在遇到 IO 操作, 控制硬件, 数组操作, 复杂运算等, 推荐在函数中增加异常处理
* 4. 如果程序要求高度的稳定性, 即决不允许出现死机, 中断等情况, 则在函数中增加异常处理
*/
private void exceptionFun()
{
try
{
// Implementation...
}
catch (Exception e)
{
e.printStackTrace();
}
finally
{
// ...
}
}
/**
* 私有方法描述...
*/
@Deprecated
private void doSomething()
{
// Implementation...
}
/**
* 保护方法描述...
*
* 1. 参数间隔的逗号","之后必须有空格(Objective-C 语言为冒号":")
* 2. 在 Eclipse 中, 注释函数时, 在函数行之前输入"/**"后, 回车, 即可自动生成注释样式
* 3. 函数的注释, 不分编程语言(C, C++, Java, Objective-C 等), 均采用 Javadoc 格式
* 4. @param 为参数说明
* 5. @return 为返回值说明
* @param nParam1 参数 1 描述...
* @param fParam2 参数 2 描述...
* @return 返回值说明
*/
protected boolean doSomething(final int nParam1, final float fParam2)
{
// Implementation...
return true;
}
/**
* 公有方法描述...
*
* 1. 对于不许在函数内部改变的参数, 则必须使用 final 描述(C 语言 const), 如 bParam1 和 dParam2
* 2. 对于可能在函数内部改变的参数, 则不能使用 final 描述, 如 strParamX
* @param bParam1 参数 1 描述...
* @param dParam2 参数 2 描述...
* @param strParamX 参数 X 描述... (注意: 请将参数, 描述都对齐)
* @return 返回值说明
*/
public String doSomething(final boolean bParam1, final double dParam2, String strParamX)
{
strParamX = "My values changed!";
// Implementation...
return strParamX;
}
/**
* 内部类...
*/
private class CodingRulerInternal
{
// ...
}
}