web前端編碼規範整合

時間 2019-11-10

標籤 web 前端編碼規範整合欄目 HTML 简体版

原文原文鏈接

決定綜合網上的規範整出一套本身的開發規範出來，之後代碼的風格均按照要求來編排，方便管理維護javascript

1、命名規範

項目命名：所有采用小寫方式，如下劃線分隔，例：my_project_name
目錄命名：參照項目命名規則；有複數結構時，要採用複數命名法。例：scripts, styles
JS文件命名：參照項目命名規則。例：account_model.js
CSS, SCSS文件命名：參照項目命名規則。例：retina_sprites.scss
HTML文件命名：參照項目命名規則。例：error_report.html
CSS命名：
通用類：使用小寫字母，以中劃線分隔。例：element-contentcss

業務類：BEM思想，block__element--modifier。例如：person__hand--lefthtml

另外：SCSS中的變量、函數、混合、placeholder採用駝峯式命名前端
ID命名：採用駝峯式命名。例：colorBlack

2、 HTML規範

2.1 html頭部聲明統一

一、 DTD聲明vue

<!DOCTYPE html>

二、頁面編碼統一java

<meta charset="UTF-8"/>

三、meta聲明jquery

PC端註明: IE兼容/keywords/descriptiongit

<meta http-equiv="X-UA-Compatible" content="IE=Edge">
  <meta name="title" content="優酷-中國領先視頻網站,提供視頻播放,視頻發佈,視頻搜索 - 優酷視頻">
  <meta name="keywords" content="視頻,視頻分享,視頻搜索,視頻播放,優酷視頻">
  <meta name="description" content="視頻服務平臺,提供視頻播放,視頻發佈,視頻搜索,視頻分享">

移動端註明：github

<meta name="viewport" content="width=device-width,initial-scale=1,maximum-scale=1,user-scalable=no">
<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
<meta name="format-detection" content="telephone=no, address=no">

四、引入CSS, JSweb

根據HTML5規範, 一般在引入CSS和JS時不須要指明 type，由於 text/css 和 text/javascript 分別是他們的默認值

HTML5 規範連接：使用link，使用style，使用script

<!-- External CSS -->
<link rel="stylesheet" href="code_guide.css">

<!-- In-document CSS -->
<style>
    ...
</style>

<!-- External JS -->
<script src="code_guide.js"></script>

<!-- In-document JS -->
<script>
    ...
</script>

2.2 風格與易讀性

一、格式縮進

html編碼統一格式化顯示，使用一個Tab鍵進行分層縮進 (2個空格寬度)，使整個頁面結構層次清晰，方便閱讀和修改。

二、模塊註釋

html較大獨立模塊之間註釋格式統一使用：

<!-- start: XXX模塊 -->

<!-- end: XXX模塊 -->

或者：

<!-- XXX模塊 -->

<!-- /XXX模塊 -->

2.3 標籤與屬性

一、因爲html標籤和屬性不區別大小寫，全部建議都採用小寫，尤爲是自定義標籤和屬性名，否認js中取不到，如：

<div data-bgColor="red"></div>

$('div').data('bgColor');  // 取不到，已自動被瀏覽器轉成了data-bgcolor

二、全部html屬性必須添加雙引號（非單引號）。

// 禁止
<div id=mainframe> 或 <div id='mainframe'>

// 推薦
<div id="mainframe">

三、標籤屬性順序

屬性應該按照特定的順序出現以保證易讀性；

class
id
name
data-*
src, for, type, href, value , max-length, max, min, pattern
placeholder, title, alt
aria-*, role
required, readonly, disabled

class是爲高可複用組件設計的，因此應處在第一位；

id更加具體且應該儘可能少使用，因此將它放在第二位

四、boolean屬性

boolean屬性指不須要聲明取值的屬性，XHTML須要每一個屬性聲明取值，可是HTML5並不須要；

boolean屬性的存在表示取值爲true，不存在則表示取值爲false。

<input type="text" disabled>

<input type="checkbox" value="1" checked>

<select>
    <option value="1" selected>1</option>
</select>

2.4 雜項

一、全部標籤必須採用合理嵌套。

// 禁止
<p><b></p></b>

// 推薦
<p><b></b></p>

// 禁止inline級標籤嵌套block級標籤
<span><div></div></span>

二、img標籤中必須添加alt屬性。如：<img src="…" alt="logo" />

三、減小標籤數量

在編寫HTML代碼時，須要儘可能避免多餘的父節點；

不少時候，須要經過迭代和重構來使HTML變得更少。

<!-- Not well -->
<span class="avatar">
    <img src="...">
</span>

<!-- Better -->
<img class="avatar" src="...">

3、 CSS代碼規範

3.1 CSS引用規範

一、全部CSS均爲外部調用，不得在頁面書寫任何內部樣式或行內樣式；

二、html頁面引入樣式文件：

統一使用link標籤，少用@import（原生import有加載性能問題），sass、less、vue.js等文件使用import命令除外（由於最終前端構建工具會將引入文件編譯成一個css文件）。

<link rel="stylesheet" href="xxx.css">
<!-- type="text/css"能夠省略，清爽 -->

3.2 CSS註釋規範

一、css頭部文檔註釋( 統一加上@charset聲明 )，以下：

@charset "utf-8";

/**
 * @created : 2017/09/15 
 * @author : Mr.Wang 
 * @version : v1.0 
 * @desc : XX模塊 
 **/

關於"version"，若是對代碼有修改更新version版本號，並添加相關注釋。

二、內部模塊之間註釋（建議 @模塊英文名，好查找）：

/* @info 商品信息區 -----------------------------------------------------------*/
.infoArea{}

/* 單行註釋 */
.specArea{}

/* @price 商品價格區 ----------------------------------------------------------*/
.price{}

3.3 CSS字符規範

一、縮進：使用soft tab（2個空格）；
二、分號：每一個屬性聲明末尾都要加分號；
三、空行:

如下幾種狀況須要空行

/**
 * 文件最後保留一個空行
 * '}'後最好跟一個空行，包括scss中嵌套的規則
 * 屬性之間須要適當的空行，具體見屬性聲明順序
 **/

.element {
    ...
}

.dialog {
    color: red;

    &:after {
        ...
    }
}

四、空格

如下幾種狀況不須要空格	如下幾種狀況須要空格
屬性名後	屬性值前
多個規則的分隔符','前	選擇器'>', '+', '~'先後
!important '!'後	'{'前
屬性值中'('後和')'前	!important '!'前
行末不要有多餘的空格	屬性值中的','後
註釋'/'後和'/'前

/* 示例代碼 */
.element,
.dialog {
  color: red !important;
  background-color: rgba(0, 0, 0, .5);
}

五、引號

最外層統一使用雙引號；

url的內容要用引號；

屬性選擇器中的屬性值須要引號。

.element:after {
    content: "";
    background-image: url("logo.png");
}

li[data-type="single"] {
    ...
}

3.4 樣式中屬性

一、排序規則：先外部 > 再自身 > 後內部

推薦工具CSScomb，sublime 和 vscode 均有對應插件

A. 影響文檔流的屬性（display, position, float, clear, visibility, table-layout等）

 B. 自身盒模型的屬性（width, height, margin, padding, border等）

 C. 排版相關屬性（font, line-height, text-align, text-indent, vertical-align等）

 D. 裝飾性屬性（color, background, opacity, cursor等）

 E. 生成內容的屬性（content, list-style, quotes等）

二、屬性簡寫

屬性簡寫須要你很是清楚屬性值的正確順序，並且在大多數狀況下並不須要設置屬性簡寫中包含的全部值，因此建議儘可能分開聲明會更加清晰；

margin 和 padding 相反，須要使用簡寫；

常見的屬性簡寫包括：font background transition animation

/* not good */
.element {
    transition: opacity 1s linear 2s;
}

/* good */
.element {
    transition-delay: 2s;
    transition-timing-function: linear;
    transition-duration: 1s;
    transition-property: opacity;
}

3.5 雜項

一、不容許有空的規則；

二、元素選擇器用小寫字母；

三、去掉小數點前面的0；

四、去掉數字中沒必要要的小數點和末尾的0；

五、屬性值'0'後面不要加單位；

六、同個屬性不一樣前綴的寫法須要在垂直方向保持對齊，具體參照右邊的寫法；

七、無前綴的標準屬性應該寫在有前綴的屬性後面；

八、不要在同個規則裏出現重複的屬性，若是重複的屬性是連續的則不要緊；

九、不要在一個文件裏出現兩個相同的規則；

十、用 border: 0; 代替 border: none;；

十一、選擇器不要超過4層（在scss中若是超過4層應該考慮用嵌套的方式來寫）；

十二、發佈的代碼中不要有 @import；

1三、儘可能少用'*'選擇器。

3、 JavaScript規範（jslint/eslint）

3.1 JS文件引用

一、引入格式：

腳本語言發展至今，也只有js混的最好了，因此type="text/javascript"類型指定能夠省去。

<script src="model.js"> </script>

二、引入位置： body標籤內最後部（非body外面）, 減小因載入腳本而形成其餘頁面內容阻塞的問題（js單線程）。

<html>
  <body>
    <div>頁面內容….</div>
    <script src="model.js"></script>
  </body>
</html>

三、引入方式：html頁面中禁止直接編寫js代碼，統一使用<script>外部引用方式，以便打包壓縮和緩存。

3.2 空格

如下幾種狀況須要空格：

二元運算符先後
三元運算符'?:'先後
代碼塊'{'前
下列關鍵字前：else, while, catch, finally
下列關鍵字後：if, else, for, while, do, switch, case, try, catch, finally, with, return, typeof
單行註釋'//'後（若單行註釋和代碼同行，則'//'前也須要），多行註釋'*'後
對象的屬性值前
for循環，分號後留有一個空格，前置條件若是有多個，逗號後留一個空格
不管是函數聲明仍是函數表達式，'{'前必定要有空格
函數的參數之間

// not good
var a = {
  b :1
};

// good
var a = {
  b: 1
};

// not good
++ x;
y ++;
z = x?1:2;

// good
++x;
y++;
z = x ? 1 : 2;

// not good
var a = [ 1, 2 ];

// good
var a = [1, 2];

// not good
var a = ( 1+2 )*3;

// good
var a = (1 + 2) * 3;

// no space before '(', one space before '{', one space between function parameters
var doSomething = function(a, b, c) {
  // do something
};

// no space before '('
doSomething(item);

// not good
for(i=0;i<6;i++){
  x++;
}

// good
for (i = 0; i < 6; i++) {
  x++;
}

3.3 JS註釋規則

一、文件頭部註釋猛戳查看詳情

/**
  * @created : 2017/09/15 
  * @author : Mr.Wang 
  * @version : v1.0 
  * @desc : 當前js模塊功能描述
  * @e.g. : 方法用例，如：$('.title').tip(); 
  **/

3.3.2 方法註釋及單行註釋

一、對於一個較複雜的方法和函數，可用採用多行註釋，以便做詳情的描述。

/** 
  * 此方法是用於解析tpl模塊
  * 經過分析html中結構… 
  **/

二、單行註釋

雙斜線後，必須跟一個空格；
縮進與下一行代碼保持一致；
可位於一個代碼行的末尾，與代碼間隔一個空格。

var funName = function(arg1, arg2) {
  this.arg1 = arg1;

  // 單行註釋說明(上面添加一空行, //與說明之間空一格)
  this.arg2 = arg2;
};

3.4 命名規則

變量名應由 26 個大小寫字母（A..Z，a..z），10 個數字（0..9），和「_」（下劃線）組成。

一、一般, 使用」駝峯式」寫法，對象、函數和實例時尤爲如此。

// 不推薦
var is_my_object = {};
var is-my-object = {};

// 推薦
var isMyObject = {};

二、構造函數或類時使用駝峯式大寫

// 不推薦
var bad = new user({
  name: 'nope'
});

// 推薦
var good = new User({
  name: 'nope'
});

三、常量大寫，並用下劃線分隔，形式如：NAMES_LIKE_THIS

四、幾種特殊命名狀況

// 'ID'在變量名中全大寫
var goodID;

// 'URL'在變量名中全大寫
var reportURL;

// 'Android'在變量名中大寫第一個字母
var AndroidVersion;

// 'iOS'在變量名中小寫第一個，大寫後兩個字母
var iOSVersion;

五、jquery對象必須以'$'開頭命名

// not good
var body = $('body');

// good
var $body = $('body');

3.5 變量聲明

一個函數做用域中全部的變量聲明儘可能提到函數首部，用一個var聲明，不容許出現兩個連續的var聲明

function doSomethingWithItems(items) {
  // use one var
  var value = 10,
      result = value + 10,
      i,
      len;

  for (i = 0, len = items.length; i < len; i++) {
    result += 10;
  }
}

3.6 null

（1）適用場景：

初始化一個未來可能被賦值爲對象的變量
與已經初始化的變量作比較
做爲一個參數爲對象的函數的調用傳參
做爲一個返回對象的函數的返回值

（2）不適用場景：

不要用null來判斷函數調用時有無傳參
不要與未初始化的變量作比較

// not good
function test(a, b) {
  if (b === null) {
    // not mean b is not supply
    ...
  }
}

var a;

if (a === null) {
  ...
}

// good
var a = null;

if (a === null) {
  ...
}

3.7 undefined

永遠不要直接使用undefined進行變量判斷；

使用typeof和字符串'undefined'對變量進行判斷。

// not good
if (person === undefined) {
  ...
}

// good
if (typeof person === 'undefined') {
  ...
}

3.8 編碼模式

爲了規範代碼嚴謹風格，推薦嚴格模式(Strict Mode)，即老是在模塊頂部聲明 'use strict';

(function(){
  'use strict';
  
  function innerFun(){
    var j = 0;
    //……
  }
});

嚴格模式的一大目標是顯性的拋出錯誤，讓你能更方便更快的調試一些隱性的錯誤。

一、防止意外的建立了全局變量。

非嚴格模式下，爲一個未申明的局部變量賦值時會自動建立一個同名的全局變量，這是Js程序中最容易出現的錯誤之一，在嚴格模式下這麼作會顯性的拋出異常。

// 嚴格模式下會拋出異常
(function() {
  some = 'foo';
}());

二、防止函數中的this指針意外指向全局。

非嚴格模式下，函數中未被定義或爲空( null or undefined)的this會默認指向全局環境(global)。

window.color = 'red';

function getColor() {
  console.log(this.color);
}

// 在嚴格模式中會報錯, 非嚴格模式中則提示red
getColor();

三、防止重名。

當編寫大量代碼時，對象屬性和函數參數很容易一不當心被設置成一個重複的名字。嚴格模式在這種狀況下會顯性的拋出錯誤

// 重複的變量名，在嚴格模式下會報錯。
function doSomething(value1, value2, value1) {
  //code
}

// 重複的對象屬性名，在嚴格模式下會報錯。
var object = {
  foo: 'bar',
  foo: 'baz'
};

四、對只讀屬性修改/刪除時會拋出異常。

ES5中可爲對象特定屬性設爲只讀或讓整個對象不可修改。但在非嚴格模式中嘗試修改一個只讀屬性只會默不作聲的失敗。

var person = {};

Object.defineProperty(person, 'name' {
  writable: false,
  value: 'Nicholas'
});

// 在非嚴格模式時，沉默的失敗，在嚴格模式則拋出異常
person.name = 'John';

五、不要在全局環境下啓用嚴格模式。

爲了兼容第三方代碼可能沒有爲嚴格模式作好準備而引起的問題，最好把開啓嚴格模式的指令做用於本身獨立的模塊/函數裏。