编程规范文档——Java版本

编码规范

1. 源文件

1. 命名与顶层类同名，大小写敏感
2. 编码格式为UTF-8

2. 格式

1. 任何命名都必须能够见文达意

2. 包名 全部小写，连续的单词只是简单地连接起来，不使用下划线

   例如 客户拜访模块，包名应为 customervisit

3. 类名 都以UpperCamelCase风格编写（缩写也只保证首字母大写）

   例1: customer visit manager
   
   public class CustomerVisitManager{
    //TO-DO
   }
   
   例2: HTTP POST thread
   public class HttpPostThread extends Thread{
    //TO-DO
   }
   

4. 方法名 都以lowerCamelCase风格编写,通常是是动词或动词短语

   例如 获取用户列表，方法名应为 
   public void queryCustomersByOutworkerId() {
   //TO-DO
   }
   

5. 常量名 全部字母大写，用下划线分隔单词

   例如 用户类型 
   private static final String TOPIC_CUSTOMER_LOCATION_CHANGED ="/customer/location/changed";
   

6. 非常量字段 名以lowerCamelCase风格编写。通常是名词或名词短语

   例如 客户拜访列表 
   private ArrayList<CustomerVisit> customerVisitings;
   private ArrayList<CustomerVisit> customerVisitingList;
   

7. 参数名 以lowerCamelCase风格编写，避免用单个字符命名

  例如  
  private CustomerVisit queryCustomerVisitById(String customerVisitId ) {
  //TO-DO
  }

3. 编程

1. 尽量降低方法复杂度，每个方法长度一般不超过50行
2. 捕获的异常：不能忽视
3. 使用类名调用静态的类成员，而不是具体某个对象或表达式
4. 每个switch语句都包含一个default语句组，即使它什么代码也不包含

4. 注释

1. 每个public类及它的每个public和protected成员处都应该使用注释或Javadoc

5. 数据库相关

1. 表名命名规则
2. 字段命名规则
3. 索引命名规则
4. 外键命名规则

建议

1. 格式

1. 小括号 在逻辑运算和数学运算中，不要省略小括号

   if((a==0)&&(b>0)||(a>100)){
    //TO-DO
   }
   

2. 大括号 与if, else, for, do, while语句一起使用，即使只有一条语句(或是空)，也应该把大括号写上，遵循Kernighan和Ritchie风格

   • 左大括号前不换行
   • 左大括号后换行
   • 右大括号前换行
   • 如果右大括号是一个语句、函数体或类的终止，则右大括号后换行; 否则不换行。例如，如果右大括号后面是else或逗号，则不换行。

2. 编程

1. 中括号是类型的一部分：String[] args， 而非String args[]
2. 每次只声明一个变量，每次声明独占一行

   不要使用组合声明，比如 int a, b;

3. 注释

1. 行尾注释使用//进行注释
2. 单行注释使用/* ... */进行注释
3. 多行注释使用/* ... */ 进行注释
4. 注释不要封闭在由星号或其它字符绘制的框架里

日志规范

1. 正确使用日志级别

   ERROR: 代码无法恢复的事件
   INFO : 重要业务事件、数据
   DEBUG: 详细的系统运行日志
   

2. 日志使用

   1. 应该打印协议的Url、Request、Response，使用INFO级别
   2. 队列任务处理应该打印入队、出队情况，使用INFO级别
   3. 数据库增、删、改操作应该打印Sql数据及数据源，使用INFO级别
   4. 严重故障应该进行单独记录、统计、告警,使用ERROR级别
   5. 重要功能、步骤要记录日志
   

3. 日志命名格式

   1. 普通日志命名：

      logs/server-name/{name}%d{yyyy-MM-dd}%i.log

   2. 数据库日志命名

      logs/server-name/sql/%d{yyyy-MM-dd/HH}.log.gz

   3. 切分规则：

      按照自然日划分日志文件，单个日志文件最大300m

   4. 日志输出格式：

      %d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n

   日志配置样例

约定语字典

References

google style

html&&css

ref1