CodingRuler

编码规范无疑是一个最最最最基础的问题，统一编码规范是任何团队首要做的事情，但实际上，无论公司大小和知名度，很多团队都没有统一规范，写出来的代码给人一种很随意，很不规范的感觉。当然，更重要的是会带来后续的维护成本。大多数情况下，我们参考JAVA编码规范即可，不过，对于刚进项目的同事来说，可能更好的是给出一个简单的模板，依葫芦画瓢即可。

以下代码仅作为了个模板参考，可以直接放到工程中去。

简单模板

SampleCode.java

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80

/*
 * Copyright (C) 2010-2013 The XXX Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.xxx.codestyle;

/**
 * 类的大体描述放在这里。
 *         
 * @author 作者名
 * @date 2014-xx-xx
 * @since v1.0.0
 */
@SuppressWarnings("unused")
public class SampleCode {

    /** 公有的常量注释 */
    public static final String ACTION_MAIN = "android.intent.action.MAIN";
    
    /** 私有的常量注释（同类型的常量可以分块并紧凑定义） */
    private static final int MSG_AUTH_NONE    = 0;
    private static final int MSG_AUTH_SUCCESS = 1;
    private static final int MSG_AUTH_FAILED  = 2;
    
    /** 保护的成员变量注释 */
    protected Object mObject0;
    
    /** 私有的成员变量 mObject1 注释（同类型的成员变量可以分块并紧凑定义） */
    private Object mObject1;
    /** 私有的成员变量 mObject2 注释 */
    private Object mObject2;
    /** 私有的成员变量 mObject3 注释 */
    private Object mObject3;
    
    /**
     * 对于注释多于一行的，采用这种方式来
     * 定义该变量
     */
    private Object mObject4;

    /**
     * 公有方法描述...
     * 
     * @param param1  参数1描述...
     * @param param2  参数2描述...
     * @param paramXX 参数XX描述... （注意：请将参数、描述都对齐）
     */
    public void doSomething(int param1, float param2, String paramXX) {
        // ...implementation
    }
    
    /**
     * 保护方法描述...
     */
    protected void doSomething() {
        // ...implementation        
    }
    
    /**
     * 私有方法描述...
     * 
     * @param param1  参数1描述...
     * @param param2  参数2描述...
     */
    private void doSomethingInternal(int param1, float param2) {
        // ...implementation        
    }
}

更加详细的描述如下

CodingRuler.java

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269

/*
 * 文件名（可选），如 CodingRuler.java
 * 
 * 版本信息（可选），如：@version 1.0.0
 * 
 * 版权申明（开源代码一般都需要添加），如：Copyright (C) 2010-2013 XXX Corporation.
 */

package com.xxx.codestyle;

/**
 * 类的大体描述放在这里。
 * 
 * <p>
 * <b>NOTE：以下部分为一个简要的编码规范，更多规范请参考 ORACLE 官方文档。</b><br>
 * 地址：http://www.oracle.com/technetwork/java/codeconventions-150003.pdf<br>
 * 另外，请使用 UTF-8 格式来查看代码，避免出现中文乱码。<br>
 * <b>至于注释应该使用中文还是英文，请自己行决定，根据公司或项目的要求而定，推荐使用英文。</b><br>
 * </p>
 * <h3>1. 整理代码</h3>
 * <ul>
 *    <li>1.1. Java 代码中不允许出现在警告，无法消除的警告要用 @SuppressWarnings。
 *    <li>1.2. 去掉无用的包、方法、变量等，减少僵尸代码。
 *    <li>1.3. 使用 Lint 工具来查看并消除警告和错误。
 *    <li>1.4. 使用 Ctrl+Shift+F 来格式化代码，然后再进行调整。
 *    <li>1.5. 使用 Ctrl+Shift+O 来格式化 Import 包。
 * </ul>
 * 
 * <h3>2. 命名规则</h3>
 *    <h3>2.1. 基本原则</h3>
 *    <ul>
 *         <li>2.1.1. 变量，方法，类命名要表义，严格禁止使用 name1, name2 等命名。
 *         <li>2.1.2. 命名不能太长，适当使用简写或缩写。（最好不要超过 25 个字母）
 *         <li>2.1.3. 方法名以小写字母开始，以后每个单词首字母大写。
 *         <li>2.1.4. 避免使用相似或者仅在大小写上有区别的名字。
 *         <li>2.1.5. 避免使用数字，但可用 2 代替 to，用 4 代替 for 等，如 go2Clean。
 *     </ul>
 *    
 *    <h3>2.2. 类、接口</h3>
 *    <ul>
 *         <li>2.2.1. 所有单词首字母都大写。使用能确切反应该类、接口含义、功能等的词。一般采用名词。
 *         <li>2.2.2. 接口带 I 前缀，或able, ible, er等后缀。如ISeriable。
 *    </ul>
 *    
 *    <h3>2.3. 字段、常量</h3>
 *    <ul>
 *         <li>2.3.1. 成员变量以 m 开头，静态变量以 s 开头，如 mUserName, sInstance。
 *         <li>2.3.2. 常量全部大写，在词与词之前用下划线连接，如 MAX_NUMBER。
 *         <li>2.3.3. 代码中禁止使用硬编码，把一些数字或字符串定义成常用量。
 *         <li>2.3.4. 对于废弃不用的函数，为了保持兼容性，通常添加 @Deprecated，如 {@link #doSomething()}
 *    </ul>
 *         
 * <h3>3. 注释</h3>
 *    请参考 {@link #SampleCode} 类的注释。
 *    <ul>
 *    <li>3.1. 常量注释，参见 {@link #ACTION_MAIN} 
 *    <li>3.2. 变量注释，参见 {@link #mObject0} 
 *    <li>3.3. 函数注释，参见 {@link #doSomething(int, float, String)}
 *    </ul> 
 *    
 * <h3>4. Class 内部顺序和逻辑</h3>
 * <ul>
 *    <li>4.1. 每个 class 都应该按照一定的逻辑结构来排列基成员变量、方法、内部类等，
 *             从而达到良好的可读性。
 *    <li>4.2. 总体上来说，要按照先 public, 后 protected, 最后 private, 函数的排布
 *             也应该有一个逻辑的先后顺序，由重到轻。
 *    <li>4.3. 以下顺序可供参考：<br>
 *         定义TAG，一般为 private（可选）<br>
 *         定义 public 常量<br>
 *         定义 protected 常量、内部类<br>
 *         定义 private 变量<br>
 *         定义 public 方法<br>
 *         定义 protected 方法<br>
 *         定义 private 方法<br>
 * </ul>        
 * 
 * <h3>5. 表达式与语句</h3>
 *    <h3>5.1. 基本原则：采用紧凑型风格来编写代码</h3>
 *    <h3>5.2. 细则</h3>
 *    <ul>
 *         <li>5.2.1. 条件表示式，参见 {@link #conditionFun(boolean)} 
 *         <li>5.2.2. switch 语句，参见 {@link #switchFun(int)}
 *         <li>5.2.3. 循环语句，参见 {@link #circulationFun(boolean)}
 *         <li>5.2.4. 错误与异常，参见 {@link #exceptionFun()}
 *         <li>5.2.5. 杂项，参见 {@link #otherFun()}
 *         <li>5.2.6. 批注，参见 {@link #doSomething(int, float, String)}
 *     </ul>
 * 
 * @author 作者名
 * @date 2014-xx-xx
 * @since v4.3.0
 */
@SuppressWarnings("unused")
public class CodingRuler {

    /** 公有的常量注释 */
    public static final String ACTION_MAIN = "android.intent.action.MAIN";
    
    /** 私有的常量注释（同类型的常量可以分块并紧凑定义） */
    private static final int MSG_AUTH_NONE    = 0;
    private static final int MSG_AUTH_SUCCESS = 1;
    private static final int MSG_AUTH_FAILED  = 2;
    
    /** 保护的成员变量注释 */
    protected Object mObject0;
    
    /** 私有的成员变量 mObject1 注释（同类型的成员变量可以分块并紧凑定义） */
    private Object mObject1;
    /** 私有的成员变量 mObject2 注释 */
    private Object mObject2;
    /** 私有的成员变量 mObject3 注释 */
    private Object mObject3;
    
    /**
     * 对于注释多于一行的，采用这种方式来
     * 定义该变量
     */
    private Object mObject4;

    /**
     * 公有方法描述...
     * 
     * @param param1  参数1描述...
     * @param param2  参数2描述...
     * @param paramXX 参数XX描述... （注意：请将参数、描述都对齐）
     */
    public void doSomething(int param1, float param2, String paramXX) {
        // 以下注释标签可以通过Eclipse内置的Task插件看到
        // TODO  使用TODO来标记代码，说明标识处有功能代码待编写
        // FIXME 使用FIXME来标记代码，说明标识处代码需要修正，甚至代码是
        //       错误的，不能工作，需要修复
        // XXX   使用XXX来标记代码，说明标识处代码虽然实现了功能，但是实现
        //       的方法有待商榷，希望将来能改进
    }
    
    /**
     * 保护方法描述...
     */
    @Deprecated
    protected void doSomething() {
        // ...implementation
    }
    
    /**
     * 私有方法描述...
     * 
     * @param param1  参数1描述...
     * @param param2  参数2描述...
     */
    private void doSomethingInternal(int param1, float param2) {
        // ...implementation        
    }
    
    /**
     * 条件表达式原则。
     */
    private void conditionFun() {
        boolean condition1 = true;
        boolean condition2 = false;
        boolean condition3 = false;
        boolean condition4 = false;
        boolean condition5 = false;
        boolean condition6 = false;
        
        // 原则： 1. 所有 if 语句必须用 {} 包括起来，即便只有一句，禁止使用不带{}的语句
        //       2. 在含有多种运算符的表达式中，使用圆括号来避免运算符优先级问题
        //       3. 判断条件很多时，请将其它条件换行
        if (condition1) {
            // ...implementation
        }
        
        if (condition1) {
            // ...implementation
        } else {
            // ...implementation
        }
        
        if (condition1)          /* 禁止使用不带{}的语句 */
            condition3 = true;
        
        if ((condition1 == condition2) 
                || (condition3 == condition4)
                || (condition5 == condition6)) {
            // ...implementation
        }
        
        if ((condition1 == condition2) 
                && (condition3 == condition4)
                && (condition5 == condition6)) {
            // ...implementation
        }
    }
    
    /**
     * Switch语句原则。
     */
    private void switchFun() {
        
        // 原则： 1. switch 语句中，break 与下一条 case 之间，空一行
        //       2. 对于不需要 break 语句的，请使用 /* Falls through */来标注
        //       3. 请默认写上 default 语句，保持完整性
        int code = MSG_AUTH_SUCCESS;
        switch (code) {
        case MSG_AUTH_SUCCESS:
            break;
            
        case MSG_AUTH_FAILED:
            break;
            
        case MSG_AUTH_NONE:
            /* Falls through */
        default:
            break;
        }
    }
    
    /**
     * 循环表达式。
     */
    private void circulationFun() {
        
        // 原则： 1. 尽量使用for each语句代替原始的for语句
        //       2. 循环中必须有终止循环的条件或语句，避免死循环
        //       3. 循环要尽可能的短, 把长循环的内容抽取到方法中去
        //       4. 嵌套层数不应超过3层, 要让循环清晰可读
        
        int array[] = { 1, 2, 3, 4, 5 };
        for (int data : array) {
            // ...implementation
        }
        
        int length = array.length;
        for (int ix = 0; ix < length; ix++) {
            // ...implementation
        }
        
        boolean condition = true;
        while (condition) {
            // ...implementation
        }
        
        do {
            // ...implementation
        } while (condition);
    }
    
    /**
     * 异常捕获原则。
     */
    private void exceptionFun() {
        
        // 原则： 1. 捕捉异常是为了处理它，通常在异常catch块中输出异常信息。
        //       2. 资源释放的工作，可以放到 finally 块部分去做。如关闭 Cursor 等。
        try {
            // ...implementation
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            
        }
    }
    
    /**
     * 其它原则（整理中...）。
     */
    private void otherFun() {
        // TODO
    }    
}
Android
Android, CodingRuler