代码规范

最新推荐文章于 2022-04-30 20:55:16 发布

原创最新推荐文章于 2022-04-30 20:55:16 发布 · 468 阅读

CC 4.0 BY-SA版权

/** 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;

/**
 * 类的基本描述写在这里...
 * <p>
 * <h3>1. 代码</h3>
 * <ul>
 *     <li>1.1. 请使用 UTF-8 格式来编写代码, 避免出现中文乱码
 *     <li>1.2. 代码缩进必须使用 Tab, 而不能使用空格, 且代码布局尽量对齐
 *     <li>1.3. 代码中不允许出现警告(Java 代码中无法消除的警告要用 @SuppressWarnings)
 *     <li>1.4. 去掉无用的包(命名空间), 方法(函数), 变量(字段)等, 减少僵尸代码
 *     <li>1.5. 在 Eclipse 中使用 Lint 工具来查看并消除警告和错误
 *     <li>1.6. 在 Eclipse 中使用 Ctrl+Shift+F 来格式化代码, 然后再进行调整
 *     <li>1.7. 在 Eclipse 中使用 Ctrl+Shift+O 来格式化 import 包
 * </ul>
 * 
 * <h3>2. 命名规则</h3>
 *     <h3>2.1. 基本原则</h3>
 *     <ul>
 *         <li>2.1.1. 变量, 方法, 类和接口等, 其命名要表义, 不能使用 name1, name2 等无直接意义的命名
 *         <li>2.1.2. 命名不能太长, 适当使用简写或缩写, 如 nMaximumNumber 简写为 nMaxNum
 *         <li>2.1.3. 方法名以小写字母开始, 其后每个单词首字母大写(即使用驼峰表示法), 如 doSomething
 *         <li>2.1.4. 方法名避免使用相似或者仅在大小写上有区别的名字
 *         <li>2.1.5. 方法名避免使用数字, 但可用 2 代替 to, 用 4 代替 for 等, 如 str2int
 *     </ul>
 * 
 *     <h3>2.2. 类, 接口</h3>
 *     <ul>
 *         <li>2.2.1. 所有单词首字母都大写, 使用能确切表示该类, 接口含义, 功能等的词, 一般采用名词
 *         <li>2.2.2. 接口带 I 或 On 等前缀, 或 Listener 等后缀, 如 OnClickListener
 *     </ul>
 * 
 *     <h3>2.3. 常量, 变量</h3>
 *     <ul>
 *         <li>2.3.1. 常量全部大写, 在单词与单词之间用下划线连接, 如 MAX_NUMBER
 *         <li>2.3.2. 变量前使用前缀 m_ 标识为成员变量, 如果是静态成员变量则为 ms_, 如 m_strUserName, ms_instance
 *         <li>2.3.3. 普通变量使用前缀 n, f, d, b, bt, str 等标识变量的数据类型, 如 nNum, strName
 *         <li>2.3.4. 某些局部变量可以根据实际情况灵活变通, 比如用于循环中的 i, j, k 等变量
 *         <li>2.3.5. 代码中禁止使用硬编码, 应把一些数字或字符串定义成常用量, 如圆周率等
 *         <li>2.3.6. 对于废弃不用的函数, 为了保持兼容性, 通常添加 @Deprecated, 如 {@link #doSomething()}
 *     </ul>
 *
 * <h3>3. 注释</h3>
 *     请参考 {@link #SampleCode} 类的注释
 *     <ul>
 *     <li>3.1. 所有的注释, 不分编程语言(C, C++, Java, Objective-C 等), 均采用 Javadoc 格式
 *     <li>3.2. 在代码的关键函数部分, 逻辑处理部分, 复杂算法部分等, 必须添加注释
 *     <li>3.3. 代码中的注释尽量做到"宁多勿少", 必要的时候还必须配套相应的说明文档
 *     <li>3.4. 常量注释, 参见 {@link #PUB_VAR}
 *     <li>3.5. 变量注释, 参见 {@link #m_object0}
 *     <li>3.6. 函数注释, 参见 {@link #doSomething(boolean, double, String)}
 *     <li>3.7. 注释语言, 根据项目的要求来决定应该使用中文还是英文, 对于容易产生歧义的注释推荐使用英文
 *     <li>3.8. 标点符号, 如果使用中文进行注释, 为了保持对齐应该使用英文标点符号
 *     </ul>
 * 
 * <h3>4. Class 内部顺序和逻辑</h3>
 * <ul>
 *     <li>4.1. 每个 class 都应该按照一定的逻辑结构来排列成员变量, 方法, 内部类等, 从而达到良好的可读性
 *     <li>4.2. 总体上来说, 要按照先 private, 然后 protected, 最后 public, 先常量后变量
 *     <li>4.3. 函数的排布也应该有一个逻辑的先后顺序, 由轻到重, 或按照调用关系的先后顺序排列
 *     <li>4.4. 以下顺序可供参考:<p>
 *         定义 TAG, 一般为 private(可选)<br>
 *         定义 private 常量<br>
 *         定义 protected 常量<br>
 *         定义 public 常量<br>
 *         定义 private 变量<br>
 *         定义 protected 变量<br>
 *         定义 public get 方法<br>
 *         定义 public set 方法<br>
 *         定义 class 的构造方法<br>
 *         定义 private 方法<br>
 *         定义 protected 方法<br>
 *         定义 public 方法<br>
 *         定义 private 内部类, 参见 {@link #CodingRulerInternal}<br>
 * </ul>
 * 
 * <h3>5. 表达式与语句</h3>
 *     <h3>5.1. 基本原则: 采用紧凑型风格来编写代码</h3>
 *     <h3>5.2. 细则</h3>
 *     <ul>
 *         <li>5.2.1. 条件表示式, 参见 {@link #conditionFun()}
 *         <li>5.2.2. switch 语句, 参见 {@link #switchFun()}
 *         <li>5.2.3. 循环语句, 参见 {@link #circulationFun()}
 *         <li>5.2.4. 错误与异常, 参见 {@link #exceptionFun()}
 *         <li>5.2.5. 其它, 参见 {@link #doSomething(boolean, double, String)}
 *     </ul>
 */
@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;

	/**
	 * 对于注释多于一行的, 采用这种方式<p>
	 * 定义该变量
	 */
	protected Object m_object4 = null;

    /**
     * get 方法描述...
     * @return
     */
	public Object getObject0()
	{
		return m_object0;
	}

    /**
     * set 方法描述...
     * <p>
     * 1. 如果是 get 或 set 函数, 函数体可以只有一行, 且可以不用写参数说明和返回值说明<p>
     * 2. 如果变量为 boolean(布尔) 型, 则 get 函数一般写为 is 前缀, 如 m_bHex 变量的函数写为 isHex()<p>
     * 3. 除了数组初始化之外, 其余用到花括号"{}"的, 必须另起一行<p>
     * 4. 比如不能使用类似 if (bClose) { 这样的代码行, 必须把 { 另起一行
     * @param obj
     */
	public void setObject0(Object obj)
	{
		m_object0 = obj;
	}

	/**
	 * 构造方法
	 */
	public CodingRuler()
	{
		// ...
	}

	/**
	 * if 条件表达式原则<p>
	 * 1. 通常 if 语句必须用花括号"{}"包括起来, 如果只有一句, 且为简单赋值或返回等, 可以使用不带 {} 的语句<p>
	 * 2. 在含有多种运算符的表达式中, 使用圆括号来避免运算符优先级问题<p>
	 * 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 语句原则<p>
	 * 1. switch 语句中, break 与下一条 case 之间, 空一行<p>
	 * 2. 对于不需要 break 语句的, 请相连使用<p>
	 * 3. 请默认写上 default 语句, 保持完整性<p>
	 * 4. 在每一个 case 语句上写注释
	 */
	private void switchFun()
	{
		int nMsg = MSG_NONE;
		
		switch (nMsg)
		{
		// 无
		// 失败
		case MSG_NONE:
		case MSG_FAILED:
			break;

		// 成功
		case MSG_SUCCESS:
			break;

		default:
			break;
		}
	}

	/**
	 * 循环表达式原则<p>
	 * 1. 尽量使用 for each 语句代替原始的 for 语句<p>
	 * 2. 循环中必须有终止循环的条件或语句, 避免死循环<p>
	 * 3. 循环要尽可能的短, 把长循环的内容抽取到方法中去<p>
	 * 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);
	}

	/**
	 * 异常捕获原则<p>
	 * 1. 捕捉异常是为了处理它, 通常在异常 catch 块中输出异常信息<p>
	 * 2. 资源释放的工作, 可以放到 finally 块部分去做, 如关闭 OutputStream 等<p>
	 * 3. 一般在遇到 IO 操作, 控制硬件, 数组操作, 复杂运算等, 推荐在函数中增加异常处理<p>
	 * 4. 如果程序要求高度的稳定性, 即决不允许出现死机, 中断等情况, 则在函数中增加异常处理
	 */
	private void exceptionFun()
	{
		try
		{
			// Implementation...
		}
		catch (Exception e)
		{
			e.printStackTrace();
		}
		finally
		{
			// ...
		}
	}
	    
	/**
	 * 私有方法描述...
	 */
	@Deprecated
	private void doSomething()
	{
		// Implementation...
	}

	/**
	 * 保护方法描述...
	 * <p>
	 * 1. 参数间隔的逗号","之后必须有空格(Objective-C 语言为冒号":")<p>
	 * 2. 在 Eclipse 中, 注释函数时, 在函数行之前输入"/**"后, 回车, 即可自动生成注释样式<p>
	 * 3. 函数的注释, 不分编程语言(C, C++, Java, Objective-C 等), 均采用 Javadoc 格式<p>
	 * 4. @param 为参数说明<p>
	 * 5. @return 为返回值说明
	 * @param nParam1 参数 1 描述...
	 * @param fParam2 参数 2 描述...
	 * @return 返回值说明
	 */
	protected boolean doSomething(final int nParam1, final float fParam2)
	{
		// Implementation...
		
		return true;
	}

	/**
	 * 公有方法描述...
	 * <p>
	 * 1. 对于不许在函数内部改变的参数, 则必须使用 final 描述(C 语言 const), 如 bParam1 和 dParam2<p>
	 * 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
	{
		// ...
	}
}