JAVA 編碼規範 1.0 (jetbrick 版) 轉載

1 JAVA 編碼規範 1.0 (jetbrick 版)

1.1 Java 文件格式

1. 文件格式必須是 UTF-8，無 BOM 格式
2. 文件回車換行符必須是 Unix 風格
3. 每個文件結尾必須有一個空白行
4. 行尾空白內容應該被 trim 掉

5. 每個文件開頭必須寫上項目的標準 LICENSE 註釋，如下：

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19

   /**  * jetbrick-template  * http://subchen.github.io/jetbrick-template/  *  * Copyright 2010-2013 Guoqiang Chen. All rights reserved.  * Email: [email protected]  *  * 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.  */

6. 代碼必須是格式化的，請使用統一的 Eclipse 的代碼格式文件：eclipse-jetbrick-style-formatter.xml

7. 不想被自動格式化的代碼請用 @formatter 包裹，如：

   1 2 3 4 5 6 7 8

   //@formatter:off private static final String[] DATE_PATTERNS = new String[] {     "yyyy-MM-dd HH:mm:ss.SSS",     "yyyy-MM-dd HH:mm:ss",     "yyyy-MM-dd",     "HH:mm:ss" }; //@formatter:on

8. Java 文件必須是可編譯的，不應該有任何的 warning 存在

1.2 包名

1. 包名必須是全部小寫的，最好用一個單詞表示
2. 包名必須以 jetbrick 開頭
3. 接口或者抽象類的多種實現，推薦以 spi, support 包命名

1.3 類名

1. 類名必須首字母大寫，駝峯命名法： 如 UserInfo，ClassUtils
2. 類名儘量不要縮寫，如果縮寫，必須爲特別常用的縮寫
3. 接口的命名不要以 I 開頭
4. 抽象類推薦以 Abstract 開頭
5. 接口的默認實現推薦以 Default 開頭或者 Impl 結尾
6. 每個 Class 都需要標註 @auther, @since
7. 每個 Class 都應該有簡短的註釋

1.4 Imports

1. Imports 間不要有空行
2. 超過 3 個相同包下面的 Class 需要使用 .* 代替
3. 不要使用 import static, 除了 JUnit / TestNG 的 assertXXX 方法

1.5 方法

1. 方法名稱應該採用首字母小寫，駝峯命名法： 如 getUser，lookupClass
2. 對於一個 public 的方法，都應該對參數進行基本的校驗，比如 null 檢測
3. 對外開放 API 的 public 方法都需要標註 @since
4. 每個 public 方法都應該有簡短的註釋

1.6 常量

1. 常量必須是全大寫，並用 _ 分隔，如 MAX_INTEGER
2. 常量必須是 static final

1.7 變量

1. 變量名稱必須首字母小寫，駝峯命名法
2. 變量名儘量使用縮寫，以簡短爲主
3. 不要用拼音，要用英文表示
4. 如果是集合或數組，用複數名詞，或者添加 List, Map 等後綴

1.8 註釋

1. 註釋必須和代碼保持一致，中文/英文均可
2. 註釋中的第一個句子要以（英文）句號、問號或者感嘆號結束。 javadoc 工具會將註釋中的第一個句子放在方法彙總表和索引中。
3. 如果註釋中有超過一個段落，用 <p> 標籤分隔
4. 如果註釋中有多個章節，用 <h2> 標籤聲明每個章節的標題
5. 示例代碼以 <pre> 包裹

1.9 異常

1. 異常類名必須以 Exception 結尾
2. 所有自定義異常都必須繼承自 RuntimeException
3. 方法儘量不要拋出非 RuntimeException 異常
4. 異常應該和主要的 Class 放在一起，而不是所有的異常類放在一個包下面
5. 異常描述應該使用英文句子，儘量不要用中文。
6. 被 catch 住的 Exception，必須要處理，或者重新拋出

1.10 日誌

1. 日誌框架使用 slf4j
2. 實例不多的對象類，不要使用 static 聲明 log
3. 儘量使用 debug 而不是 info 級別
4. 啓動時候需要輸出的重要日誌，請用 info 級別
5. 被 catch 住的 Exception，應該被打印出來 log.error(e)

1.11 單元測試

1. 單元測試框架用 TestNG
2. 單元測試覆蓋率工具用 EclEmma
3. Mock 框架使用 Mockito
4. 儘可能爲每個方法提供單元測試
5. 覆蓋率應該不低於 70%