Java代码规范

Java代码规范

• 前言
• 第一章 JAVA语言编程规范总则
• 第二章 排版规范
• 第三章 注释规范
• 第四章 命名规范
• 第五章 编码规范
• 第六章 JTEST规范
• 第七章 安全检查错误
  • 1. Portability Flaw: File Separator
  • 2. Poor Error Handling: Return Inside Finally
  • 3. PATH_MANIPULATION

前言

1. 好代码的标准（公司顺序） 简洁：易于理解、易于实现； 可维护：软件被修改的能力，包括纠错、改进、新需求或功能规格变化的适应能力； 可靠：软件在给定时间间隔和环境条件下，按设计要求成功运行程序的概率； 可测试：软件发现故障并隔离、定位故障的能力，以及在一定的时间和成本前提下，进行测试设计、测试执行的能力； 高效：尽可能少地占用系统资源，包括内存和执行时间； 可移植：为了在原来设计的特定环境之外运行，对系统进行修改的能力。
2. 举例 （1）魔鬼数字：变量命名需要有含义，直观； （2）嵌套层次深：使用卫句提前终止； （3）迭代器使用后置++效率低：使用前置++，多一个临时变量； （4）循环条件做函数调用，效率低：提前用一个变量存（问题：C++的size方法为一个复杂度O(n)的遍历）；· （5）单行注释要与前/后面代码空一行；
3. 代码可视化指标 圈复杂度CC：[1,10]，平均CC必须小于15 嵌套层数：[1,4] 有效注释比例：[0,20%] 有效代码行数（函数封装）：[1,50] 函数参数个数：[1,5] 函数变量的个数：[1,5] 非结构化语言的数量：[0,0]
4. 高质量代码 设计 编码：DRY原则（Don’t Repeat Yourself）、童子军规则（Leave the code cleaner than you found it，破窗理论）、Clean Code 过程：细心、代码质量可视化、持续改进（重构，保持代码易读、易修改）
5. 重构方法 （1）拆分函数 单一职责原则，改变接口会影响调用者，慎重。 （2）重命名函数 （3）提炼函数 函数内部单独部分拆分成函数。 机会点：if/for/switch等集中的地方、根据局部变量或全局变量按图索骥、重复代码和结构。 （4）分解条件式 （5）合并条件式 多个判断提炼为一个独立函数。 （6）合并重复的条件片段 （7）正确使用临时变量（命名规范）

第一章 JAVA语言编程规范总则

本规范总则的示例采用以下的术语描述： ★ 规则：编程时强制必须遵守的原则。 ★ 建议：编程时必须加以考虑的原则. ★ 格式：对此规范格式的说明。 ★ 说明：对此规则或建议进行必要的解释。 ★ 示例：对此规则或建议从正、反两个方面给出例子。

第二章 排版规范

2.1规则

1. *程序块要采用缩进风格编写，缩进的空格数为4个。
2. *分界符（如大括号‘{’和‘}’）应各独占一行并且位于同一列，同时与引用它们的语句左对齐。在函数体的开始、类和接口的定义、以及if、for、do、while、switch、case语句中的程序都要采用如上的缩进方式。
3. *较长的语句、表达式或参数（>80字符）要分成多行书写，长表达式要在低优先级操作符处划分新行，操作符放在新行之首，划分出的新行要进行适当的缩进，使排版整齐，语句可读。

public static LogIterator read(String logType, Date startTime,	Date endTime,
                               int logLevel, String userName, int bufferNum)
{
    if (filename != null
        && new File(logPath + filename).length() < LogConfig.getFileSize())
    {
        ... // program code
    }
}

1. *不允许把多个短语句写在一行中，即一行只写一条语句.
2. *if, for, do, while, case, switch, default 等语句自占一行，且if, for, do, while等语句的执行语句无论多少都要加括号{}。
3. *相对独立的程序块之间、变量说明之后必须加空行。
4. *对齐只使用空格键，不使用TAB键，支持行首TAB替换成空格，应将该选项打开。
5. *在两个以上的关键字、变量、常量进行对等操作时，它们之间的操作符之前、之后或者前后要加空格；进行非对等操作时，如果是关系密切的立即操作符（如.），后不应加空格。

说明：采用这种松散方式编写代码的目的是使代码更加清晰（相对的）。在已经非常清晰的语句中没有必要再留空格，如果语句已足够清晰则括号内侧(即左括号后面和右括号前面)不需要加空格，多重括号间不必加空格，因为在Java语言中括号已经是最清晰的标志了。 在长语句中，如果需要加的空格非常多，那么应该保持整体清晰，而在局部不加空格。给操作符留空格时不要连续留两个以上空格。

示例：
(1) 逗号、分号只在后面加空格。
int a, b, c;

(2)比较操作符, 赋值操作符"="、 "+="，算术操作符"+"、"%"，逻辑操作符"&&"、"&"，位域操作符"<<"、"^"等双目操作符的前后加空格。
if (current_time >= MAX_TIME_VALUE)
a = b + c;
a *= 2;
a = b ^ 2;

(3)"!"、"~"、"++"、"--"、"&"（地址运算符）等单目操作符前后不加空格。
flag = !isEmpty; // 非操作"!"与内容之间
i++;             // "++","--"与内容之间

(4)"."前后不加空格。
p.id = pid;     // "."前后不加空格

(5) if、for、while、switch等与后面的括号间应加空格，使if等关键字更为突出、明显。
if (a >= b && c > d)

2.2建议

1. 类属性和类方法不要交叉放置，不同存取范围的属性或者方法也尽量不要交叉放置。

格式：
类定义
{
类的公有属性定义
类的保护属性定义
类的私有属性定义
类的公有方法定义
类的保护方法定义
类的私有方法定义
}

第三章 注释规范

3.1规则

3.2 建议

第四章 命名规范

4.1 规则

4.2 建议

第五章 编码规范

5.1 规则

5.2建议

第六章 JTEST规范

6.1 规则（1-2 级）

6.2 建议（3级或以上）

第七章 安全检查错误

1. Portability Flaw: File Separator

可移植性缺陷：文件分割符，不同的操作系统使用不同的字符作为文件分隔符。例如，Microsoft Windows 系统使用“\”，而 UNIX 系统则使用“/”，硬编码文件分隔符会导致应用程序逻辑执行错误。

// 错误
File file = new File(directoryName + "\\" + fileName);
// 修改
File file = new File(directoryName + File.separator + fileName);

2. Poor Error Handling: Return Inside Finally

finally 块中的返回指令会导致从 try 块中抛出的异常丢失。

public static void doSomeThing() throws Exception {
　　try 
　　　　throw new Exception(“Something error!”);	//1.抛出异常
　　}catch(Exception e){							//2.捕获异常匹配，进入控制块
     　throw e;
　　}finally {									//3.throw前控制转移到finally块，执行完后再返回
　　　　return true;								//4.控制转移，直接return，不再返回catch块，吃掉了异常
　　}
}

3. PATH_MANIPULATION

使用了用户控制的字符串作为部分或全部的文件系统路径、文件名或 URI（统一资源标识符）。

1. 场景一 如果当前的用户能够访问服务器上的所有的文件，则不存在路径控制的风险，则为误报。
2. 场景二 用户只能访问有限的文件，需要验证用户的路径是否包含（“…/”和 “./”）这种相对路径字符串。
3. 场景三 用户只能访问某些特定的文件，则需要建立白名单列表，验证用户输入的文件路径是否在白名单内，不在白名单内则直接返回。

// 修改方案：（1）对路径进行校验；（2）使用FileUtils.getFile来获取文件，org.apache.commons.io.FileUtils包下的类FileUtils。使不可信的文件输入路径 变成可信的文件输入。
public class Main {
    public static void main(String[] args) throws Exception {
        String dir = "opt/test/.././..\\.\\";
        String REGEX = ".*(\\.\\.(\\/|\\\\)|\\.(\\/|\\\\)).*";
        System.out.println(dir);
        File dirFile1 = null;
        if (dir.matches(REGEX)) {
            throw new Exception("Urgent! Exist PATH_MANIPULATION safety problem!!!");
        }
        dirFile1 = FileUtils.getFile(dir);
        System.out.println(dirFile1.toString());
    }
}