编码规范

 

## Javascript 篇
### 命名规范
* `强制` 杜绝完全不规范的缩写，避免望文不知义(随意缩写会严重降低了代码的可阅读性)。

* `强制` 代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。
> 说明：正确的英文拼写和语法可以让阅读者易于理解，避免歧义。注意，即使纯拼音命名方式也要避免采用。

 > 正例：
	`taobao`、`youku`、`guangzhou`  // 等国际通用的名称，可视同英文。

 > 反例：
	`DaZhePromotion` (打折)  `setPingfen` (评分)

* `强制` `javascript` 方法(函数)名、参数名、变量都统一使用lowerCamelCase风格(小驼峰命名)，必须遵从驼峰形式。
 > 正例： localValue / getHttpMessage() / inputUserId

* `强制` 函数命名采用动词 ＋ 名词形式进行命名, 确保望文知义

    > 正例:

    ```js
    isSelected();  // 返回值为bool类型
    canUpdate();  // 返回值为bool类型
    hasNext(); // 返回值为bool类型
    getAccount();  // 返回值为一个Account 对象
    getUserList();  // 返回值为一个 用户列表
    setValue(); // 设置操作
    changeDoctorName(); // 修改医生名称
    ```


* `强制` 类名使用帕斯卡命名`PascalCase`，必须遵从驼峰形式

* `强制` 常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长。
> 正例：MAX_PAGE_COUNT
反例: MAX_COUNT

* `强制` 方法体中的私有变量以下划线`_`开始

### 格式规约
* `强制` 文件必须为`utf-8`格式
* `强制` `if/for/while/switch/do`等保留字与左右括号之间都必须加空格。
* `强制` 大括号的使用约定。如果是大括号内为空，则简洁地写成{}即可，不需要换行；如果是非空代码块则：

	1. 左大括号前不换行。
	2. 左大括号后换行。
	3. 右大括号前换行。
	4. 右大括号后还有`else`等代码则不换行；表示终止右大括号后必须换行。

	> 正例
	```
	if (condition1) {
	  doSomething1();
	}

	if (condition2) {
	  doSomething2();
	} else {
	  doSomething3();
	}
	```


* `强制` 任何运算符左右必须加一个空格。 说明：运算符包括赋值运算符`=`、逻辑运算符`&&`、加减乘除符号、三目运行符等。

* `强制` 以单引号('')嵌套双引号("")， 优先使用单引号。

* `强制` 语句结尾必须加上分号;

* `强制` 单行内容长度超出(约80个字符)必须多行显示。换行时需遵循以下规则:
	1. 第二行相对一缩进2个空格，从第三行开始不再继续缩进参考示例。
	2. 运算符与下文一起换行。
	3. 方法调用的点符号不要与下文一起换行，放在行尾。
	4. 在多个参数超长，逗号后进行换行。
	5. 在括号前不要换行，见反例。

    > 正例:
	```js
		// 超过80个字符的情况下，换行缩进2个空格
		let _introduction = getDoctorUserInfoState(getState()).
		  personalIntroduction;

		// 参数很多的方法调用可能超过80个字符，换行缩进2个空格
		method(args1, args2, args3, ...,
		  argsX);
			
		// 三目运算式可能超过80个字符，换行缩进2个空格
		 xxxxx运算式xxxx....
		   ? 表达式1
		   ：表达式2
		   
	```

	> 反例：
  	```js
		
		// 超过80个字符的情况下，不要在括号前换行
		let _introduction = getDoctorUserInfoState
			(getState()).personalIntroduction;
		// 参数很多的方法调用可能超过80个字符，不要在逗号前换行
		method(args1, args2, args3, ...
		, argsX);
	```

* `强制` 方法参数在定义和传入时，多个参数逗号后边必须加空格。

    > 正例:
    ```js
	// 下例中实参的'a', 后边必须要有一个空格。
	method('a', 'b', 'c');
	```

* `强制` 方法体内的执行语句组、变量的定义语句组、不同的业务逻辑之间或者不同的语义之间插入一个空行。相同业务逻辑和语义之间不需要插入空行。

 > 说明：没有必要插入多行空行进行隔开。

 > 正例:

 ```js

     if (condition1) {
       for (var i = 0; i < a.length; i++) {
    	 p = a[i];
    	 // 赋值操作
    	 q = a[i+1]; 
    
    	 if (codition2) {
    	   dosomething();  
    
    	 } else if (conditionElse) {
    	   dosomethingElse();
    	   dosomethingElse();
    	   dosomethingElse();
    	 }
       }
     }

```

### 控制语句
* `强制` 在一个switch块内，每个case要么通过break/return等来终止，要么注释说明程序将继续执行到哪一个case为止；在一个switch块内，都必须包含一个default语句并且放在最后，即使它什么代码也没有。

* `推荐` 推荐尽量少用else， if-else的方式可以改写成：

    ```js

    	if(condition){
    	...
    	return obj;
    	}
    	// 接着写else的业务逻辑代码;

    ```
    
    > 说明：如果非得使用if()...else if()...else...方式表达逻辑，`强制` 请勿超过3层。

### 注释规约

* `强制` 类、类属性、类方法的注释必须使用[JSDoc规范](https://ask.dcloud.net.cn/article/129)，使用`/**内容*/`格式，不得使用`//xxx`方式。

* `强制` 方法内部单行注释，在被注释语句上方另起一行，使用`//`注释
* `强制` 多行注释内容和*之间有一个空格
> 正例:

```js

    /**
     * 第一行内容
     * 第二行内容
     */  
```

* `强制` 注释掉的代码尽量要配合说明，而不是简单的注释掉。
> 说明：代码被注释掉有两种可能性：
> 1. 后续会恢复此段代码逻辑。
> 2. 永久不用。前者如果没有备注信息，难以知晓注释动机。后者建议直接删掉（代码仓库保存了历史代码）。

* `强制` 好的命名、代码结构是自解释的，注释力求精简准确、表达到位。避免过多过滥的注释。

* `推荐` 注释时如用中文注释，专有名词与关键字请保持英文原文。

### 其他

* 函数的书写规范
	* 函数内变量先声明再使用，声明位置统一放在函数开始位置
	* 函数遵循先声明后调用原则
	* 函数遵循“(只解决一件事)[https://www.cnblogs.com/freephp/p/5094979.html]”原则
	* 函数体内不要存在不同(抽象层级)[https://www.cnblogs.com/MNewLife/p/8496230.html]的函数
	* 函数命名准确描述本函数做的那件事


## CSS 篇

### 命名规范
* `强制` id 与类名使用小写字母，以中划线 - 分隔
* `强制` 元素选择器用小写字母

### 格式规约

* `强制` 文件必须为`utf-8`格式
* `强制` 缩进采用2个空格，禁止使用tab字符。
* `强制` 语句结尾必须加上分号;
* `强制` `:` 与属性值之间需要空格，与属性名之间不需要空格
* `强制` 属性值中的 `,` 后需要空格，`,` 前不需要空格
* `强制` 选择器 `>` `+` `~` 等前后需要空格
* `强制` 选择器与 `{` 之间需要空格
* `参考` `/` 前后需要空格 (安卓会有兼容问题慎用)
    > 正例:
    ```css

    .selector > .wrapper {
      font-family: "Hiragino Sans GB", sans-serif;
      background: rgba(0, 0, 0, 0.5) url(logo.png) no-repeat center / contain;
      height: 100%;
    }
    ```
    
* `强制` 两个选择器属性块之间保留一个空行，代码块注释前与代码块后保留一个空行
    > 正例:
    ```css

    .wrapper {
      height: 100%;
    
      /* 字体相关 */
      font-family: 'DINPro';
      font-size: 16px;
      font-weight: 700;
      background: #000;
    }
    
    .selector {
      height: 100%;
    }
    ```
* `强制` `{` 后需要换行，`}` 前需要换行
* `强制` 16 进制颜色尽量使用简写
* `强制` 不允许有空的规则
* `强制` 属性值 0 后面不要加单位
* `推荐` 减少CSS的层级，尽可能控制在二级，避免超过三级。
* `推荐` 属性声明顺序
    > 影响文档流的属性（比如：`display / position / float / clear / visibility` 等）
    自身盒模型的属性（比如：`width / height / margin / padding / border` 等）
    排版相关属性（比如：`font / line-height / text-align / vertical-align` 等）
    装饰性属性（比如：`color / background / opacity / cursor` 等） 
    CSS3 新特性（比如：`transform / transition / animation` 等）

### 注释规约

* `强制` 统一使用 `/* */` 进行注释, `*`号与注释内容间隔一个空格; 单行注释可位于一个代码行的末尾，与代码间隔一个空格，与注释内容也间隔一个空格
* `强制` 缩进与下一行代码保持一致