Android技术积累:开发规范

WesleyEGVP 8年前
   <p>来自: <a href="/misc/goto?guid=4959670127157316135" rel="nofollow">http://www.jianshu.com/p/b86f7a2e2c5f</a></p>    <p>上个月发布了Android项目重构的三篇系列文章,其中, <a href="/misc/goto?guid=4958971330512530106" rel="nofollow,noindex">界面篇</a> 中提到了在项目中保持规范性的重要性,也有简单举了几个例子。这篇文章则将其延伸,提供更完整的开发规范说明。</p>    <h2>书写规范</h2>    <p>1.编码方式统一用 UTF-8 . Android Studio默认已是 UTF-8 ,只要不去改动它就可以了。</p>    <p><img src="https://simg.open-open.com/show/d2a5bb674ab3519cca6129f895994b81.png"></p>    <p>2.缩进统一为 4 个空格,将 Tab size 设置为 4 则可以保证tab键按 4 个空格缩进。另外,不要勾选上 Use tab character ,可以保证切换到不同tab长度的环境时还能继续保持统一的 4 个空格的缩进样式。</p>    <p><img src="https://simg.open-open.com/show/effbf6042c77a218a20f213545e64394.png"></p>    <p>3.花括号不要单独一行,和它前面的代码同一行。而且,花括号与前面的代码之间用一个空格隔开。</p>    <pre>  public void method() { // Good     }     public void method()  { // Bad  }      public void method(){ // Bad    }</pre>    <p>4.空格的使用</p>    <pre>  // Good  if (booleanVariable) {      // TODO while booleanVariable is true  } else {      // TODO else  }    // Bad  if(booleanVariable) {      // TODO while booleanVariable is true  }else {      // TODO else  }</pre>    <p>运算符两边各用一个空格隔开。</p>    <pre>  int result = a + b; //Good, = 和 + 两边各用一个空格隔开  int result=a+b; //Bad,=和+两边没用空格隔开</pre>    <p>方法的每个参数之间用一个空格隔开。</p>    <pre>  public void method(String param1, String param2); // Good,param1后面的逗号与String之间隔了一个空格  method(param1, param2); // Good,方法调用时,param1后面的逗号与param2之间隔了一个空格  method(param1,param2); // Bad,没有用一个空格隔开</pre>    <p>5.空行的使用</p>    <p>将逻辑相关的代码段用空行隔开,以提高可读性。空行也只空一行,不要空多行。在以下情况需用一个空行:</p>    <ul>     <li>两个方法之间</li>     <li>方法内的两个逻辑段之间</li>     <li>方法内的局部变量和方法的第一条逻辑语句之间</li>     <li>常量和变量之间</li>    </ul>    <p>6.当一个表达式无法容纳在一行内时,可换行显示,另起的新行用 8 个空格缩进。</p>    <pre>  someMethod(longExpression1, longExpression2, longExpression3,            longExpression4, longExpression5);</pre>    <p>7.一行声明一个变量,不要一行声明多个变量,这样有利于写注释。</p>    <pre>  private String param1; // 参数1  private String param2; // 参数2</pre>    <p>8.行宽设置为 100 ,设置格式化时自动断行到行宽位置。</p>    <p><img src="https://simg.open-open.com/show/14bacbad454437c04a499703366ab11d.jpg"></p>    <p><img src="https://simg.open-open.com/show/a66dd7be549bb9572247771a012c84f1.jpg"></p>    <p>9.使用快捷键进行代码自动格式化。</p>    <ul>     <li>Windows: CTRL+ALT+L</li>     <li>Mac: OPTION+COMMAND+L</li>    </ul>    <p>10.一个方法最多 不要超过40行 代码。</p>    <p>11.范围型的常量用枚举类定义,而不要直接用整型或字符,这样可以减少范围值的有效性检查。</p>    <pre>  // 用枚举类定义,Good  public enum CouponType {      // 现金券      @SerializedName("1")      CASH,        // 抵用券      @SerializedName("2")      DEBIT,        // 折扣券      @SerializedName("3")      DISCOUNT  }    // 用整型定义,Bad  public static final int TYPE_CASH = 1; // 现金券  public static final int TYPE_DEBIT = 2; // 抵扣券  public static final int TYPE_DISCOUNT = 3; // 折扣券</pre>    <p>12.文字大小的单位统一用 sp ,元素大小的单位统一用 dp 。</p>    <p>13.应用中的字符串统一在 strings.xml 中定义,然后在代码和布局文件中引用。</p>    <p>14.颜色值统一在 colors.xml 中定义,然后在代码和布局文件中引用。另外,不要在代码和布局文件中引用系统的颜色,除了透明。</p>    <h2>命名规范</h2>    <p>1.包命名</p>    <p>域名反写+项目名称+模块名称 ,全部单词用小写字母。</p>    <p>例如,我的KAndroid项目的 Model 模块包名如下:</p>    <pre>  me.keeganlee.kandroid.model</pre>    <p>2.类和接口命名</p>    <p>使用大驼峰规则,用名词或名词词组命名,每个单词的首字母大写。以下为几种常用类的命名:</p>    <ul>     <li>activity 类,命名以 Activity 为后缀,如:LoginActivity</li>     <li>fragment 类,命名以 Fragment 为后缀,如:ShareDialogFragment</li>     <li>service 类,命名以 Service 为后缀,如:DownloadService</li>     <li>adapter 类,命名以 Adapter 为后缀,如:CouponListAdapter</li>     <li>工具类,命名以 Util 为后缀,如:EncryptUtil</li>     <li>模型类,命名以 BO 为后缀,如:CouponBO</li>     <li>接口实现类,命名以 Impl 为后缀,如:ApiImpl</li>    </ul>    <p>3.方法命名</p>    <p>使用小驼峰规则,用动词命名,第一个单词的首字母小写,其他单词的首字母大写。以下为几种常用方法的命名:</p>    <ul>     <li>初始化方法,命名以 init 开头,例:initView</li>     <li>按钮点击方法,命名以 to 开头,例:toLogin</li>     <li>设置方法,命名以 set 开头,例:setData</li>     <li>具有返回值的获取方法,命名以 get 开头,例:getData</li>     <li>通过异步加载数据的方法,命名以 load 开头,例:loadData</li>     <li>布尔型的判断方法,命名以 is 或 has ,或具有逻辑意义的单词如equals,例:isEmpty</li>    </ul>    <p>4.控件缩写</p>    <p><img src="https://simg.open-open.com/show/af51c1a28da267ab1e86a1a1bd8dbeca.jpg"></p>    <p>5.常量命名</p>    <p>全部为大写单词,单词之间用下划线分开。</p>    <pre>  public final static int PAGE_SIZE = 20;</pre>    <p>6.变量命名</p>    <p>{范围描述+}意义描述+类型描述 的组合,用驼峰式,首字母小写。</p>    <pre>  private TextView headerTitleTxt; // 标题栏的标题  private Button loginBtn; // 登录按钮  private CouponBO couponBO; // 券实例</pre>    <p>7.控件id命名</p>    <p>控件缩写_{范围_}意义 ,范围可选,只在有明确定义的范围内才需要加上。</p>    <pre>  <!-- 这是标题栏的标题 -->  <TextView      android:id="@+id/txt_header_title"      ... />    <!-- 这是登录按钮 -->  <Button      android:id="@+id/btn_login"      ... /></pre>    <p>8.layout命名</p>    <p>组件类型_{范围_}功能 ,范围可选,只在有明确定义的范围内才需要加上。</p>    <p>以下为几种常用的组件类型命名:</p>    <ul>     <li>activity_{范围_}功能 ,为 Activity 的命名格式</li>     <li>fragment_{范围_}功能 ,为 Fragment 的命名格式</li>     <li>dialog_{范围_}功能 ,为 Dialog 的命名格式</li>     <li>item_list_{范围_}功能 ,为 ListView 的 item 命名格式</li>     <li>item_grid_{范围_}功能 ,为 GridView 的 item 命名格式</li>     <li>header_list_{范围_}功能 ,为 ListView 的 HeaderView 命名格式</li>     <li>footer_list_{范围_}功能 ,为 ListView 的 FooterView 命名格式</li>    </ul>    <p>9.strings的命名</p>    <p>类型_{范围_}功能 ,范围可选。以下为几种常用的命名:</p>    <ul>     <li>页面标题,命名格式为: title_页面</li>     <li>按钮文字,命名格式为: btn_按钮事件</li>     <li>标签文字,命名格式为: label_标签文字</li>     <li>选项卡文字,命名格式为: tab_选项卡文字</li>     <li>消息框文字,命名格式为: toast_消息</li>     <li>编辑框的提示文字,命名格式为: hint_提示信息</li>     <li>图片的描述文字,命名格式为: desc_图片文字</li>     <li>对话框的文字,命名格式为: dialog_文字</li>     <li>menu的item文字,命名格式为: action_文字</li>    </ul>    <p>10.colors的命名</p>    <p>前缀{_控件}{_范围}{_后缀} ,控件、范围、后缀可选,但控件和范围至少要有一个。</p>    <ul>     <li>背景颜色,添加 bg 前缀</li>     <li>文本颜色,添加 text 前缀</li>     <li>分割线颜色,添加 div 前缀</li>     <li>区分状态时,默认状态的颜色,添加 normal 后缀</li>     <li>区分状态时,按下时的颜色,添加 pressed 后缀</li>     <li>区分状态时,选中时的颜色,添加 selected 后缀</li>     <li>区分状态时,不可用时的颜色,添加 disable 后缀</li>    </ul>    <p>11.drawable的命名</p>    <p>前缀{_控件}{_范围}{_后缀} ,控件、范围、后缀可选,但控件和范围至少要有一个。</p>    <ul>     <li>图标类,添加 ic 前缀</li>     <li>背景类,添加 bg 前缀</li>     <li>分隔类,添加 div 前缀</li>     <li>默认类,添加 def 前缀</li>     <li>区分状态时,默认状态,添加 normal 后缀</li>     <li>区分状态时,按下时的状态,添加 pressed 后缀</li>     <li>区分状态时,选中时的状态,添加 selected 后缀</li>     <li>区分状态时,不可用时的状态,添加 disable 后缀</li>     <li>多种状态的,添加 selector 后缀(一般为ListView的 selector 或按钮的 selector )</li>    </ul>    <p>12.动画文件命名</p>    <p>动画类型_动画方向 。</p>    <ul>     <li>fade_in ,淡入</li>     <li>fade_out ,淡出</li>     <li>push_down_in ,从下方推入</li>     <li>push_down_out ,从下方推出</li>     <li>slide_in_from_top ,从头部滑动进入</li>     <li>zoom_enter ,变形进入</li>     <li>shrink_to_middle ,中间缩小</li>    </ul>    <h2>注释规范</h2>    <p>1.文件头注释</p>    <p>文件顶部统一添加版权声明,声明的格式如下:</p>    <pre>  /**   * Copyright (c) 2015. Keegan小钢 Inc. All rights reserved.   */</pre>    <p>2.类和接口注释</p>    <p>类和接口统一添加javadoc注释,格式如下:</p>    <pre>  /**   * 类或接口的描述信息   *   * @author ${USER}   * @date ${DATE}   */</pre>    <p>3.方法注释</p>    <p>下面几种方法,都必须添加javadoc注释,说明该方法的用途和参数说明,以及返回值的说明。</p>    <ul>     <li>接口中定义的所有方法</li>     <li>抽象类中自定义的抽象方法</li>     <li>抽象父类的自定义公用方法</li>     <li>工具类的公用方法</li>    </ul>    <pre>  **   * 登录   *   * @param loginName 登录名   * @param password  密码   * @param listener  回调监听器   */  public void login(String loginName, String password, ActionCallbackListener<Void> listener);</pre>    <p>4.变量和常量注释</p>    <p>下面几种情况下的常量和变量,都要添加注释说明,优先采用 右侧// 来注释,若注释说明太长则在上方添加注释。</p>    <ul>     <li>接口中定义的所有常量</li>     <li>公有类的公有常量</li>     <li>枚举类定义的所有枚举常量</li>     <li>实体类的所有属性变量</li>    </ul>    <pre>  public static final int TYPE_CASH = 1; // 现金券  public static final int TYPE_DEBIT = 2; // 抵扣券  public static final int TYPE_DISCOUNT = 3; // 折扣券    private int id;                // 券id  private String name;           // 券名称  private String introduce;      // 券简介</pre>    <h2>结束语</h2>    <p>这份开发规范说明比较细,也许还不是非常完整,但里面提到的每一条规范都很有用。按照此规范严格执行,将大大提高代码的可读性和维护性。</p>