制定本身團隊的前端開發規範

時間 2019-11-05

標籤制定本身團隊前端開發規範简体版

原文原文鏈接

篇幅可能會比較長，可是我感受有一套規範對於一個團隊其實仍是很重要的，這樣在維護起來也會很方便，若是接下來的規範感受對大家團隊有幫助，但願能夠在團隊中進行實踐或者推薦給你的leader，代碼規範參考自：騰訊alloyteam團隊，但願你們能夠跟着看一遍，各取所需。css

後續的文章我也補充齊全了，一共有兩篇，都是實戰篇，一篇是制定本身團隊的前端開發規範之 eslint，另一篇是手摸手帶你實踐標準的前端開發規範，但願你們能夠去看一下，而後把這套規範實踐起來，讓本身的開發存在更少的bug。html

若是能夠的話，實踐過程當中有用的不舒服的，麻煩給我進行反饋，這樣才能知道這套規則適不適合大部分人去用，根據你們的意見，取其精華去其糟粕讓這套規範變得更實用。前端

命名規範

項目命名

所有采用小寫方式，如下劃線分隔。例：my_project_namevue

目錄命名

參照項目命名規則；jquery

有複數結構時，要採用複數命名法。git

例：scripts，styles，images，data_modelses6

vue的項目中，components下的組件目錄名，使用大駝峯命令github

例：LeftBar數組

JS文件命名

參照項目命名規則。瀏覽器

例：account_model.js

CSS, SCSS文件命名

參照項目命名規則。

例：retina_sprites.css

HTML文件命名

參照項目命名規則。

例：error_log.html

HTML 規範

語法：

縮進使用 tab（2 個空格）；
嵌套的節點應該縮進；
在屬性上，使用雙引號，不要使用單引號；
屬性名全小寫，用中劃線（-）作分隔符；
要在自動閉合標籤結尾處使用斜線；

<!DOCTYPE html>
<html>
  <head>
    <title>Page title</title>
  </head>
  <body>
    <img src="images/company_logo.png" alt="Company" />

    <!-- 屬性名全小寫，用中劃線（-）作分隔符 -->
    <h1 class="hello-world">Hello, world!</h1>
  </body>
</html>
複製代碼

標準模式

在開頭規定 doctype，來啓動標準模式，doctype 要大寫。

<!DOCTYPE html>
<html>
  ...
</html>
複製代碼

規定字符編碼

經過聲明一個明確的字符編碼，讓瀏覽器輕鬆、快速的肯定適合網頁內容的渲染方式，一般指定爲'UTF-8'。

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
  </head>
  ...
</html>
複製代碼

IE 兼容模式

用 meta 標籤指定頁面應該使用什麼版本的 IE 來渲染。

<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
  </head>
  ...
</html>
複製代碼

減小標籤數量

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

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

<!-- good -->
<img class="avatar" src="..." />
複製代碼

語義化標籤

html 的標籤能使用語義化的，儘可能使用語義化標籤，避免一個頁面都是 div 或者 p 標籤

<!-- bad -->
<div>
  <p></p>
</div>

<!-- good -->
<header></header>
<footer></footer>
複製代碼

CSS 規範

縮進

使用 tab 縮進（2 個空格）

.element {
  border-radius: 10px;
  width: 50px;
  height: 50px;
}
複製代碼

分號

每一個聲明結束都要加分號

.element {
  border-radius: 10px;
  width: 50px;
  height: 50px;
}
複製代碼

註釋

註釋統一使用 /* */

.element {
  /* border-radius: 10px; */
  width: 50px;
  height: 50px;
}
複製代碼

引號

url 的內容要用引號
屬性選擇器中的屬性值須要引號

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

li[data-type="single"] {
  ...;
}
複製代碼

命名

類名使用小寫字母，以中劃線分隔
id 採用駝峯式命名
scss 中的變量、函數、混合、placeholder 採用駝峯式命名

/* class */
.element-content {
  ...;
}

/* id */
#myDialog {
  ...;
}

/* 變量 */
$colorBlack: #000;

/* 混合 */
@mixin centerBlock {
  ...;
}
複製代碼

JavaScript 規範

縮進

使用 tab 縮進（2 個空格）

if (x < y) {
  x += 10;
} else {
  x += 1;
}
複製代碼

變量命名

標準變量採用駝峯式命名
'Android'在變量名中大寫第一個字母
'iOS'在變量名中小寫第一個，大寫後兩個字母
常量全大寫，用下劃線鏈接
構造函數，大寫第一個字母
jquery 對象必須以'$'開頭命名

var thisIsMyName;

var AndroidVersion;

var iOSVersion;

var MAX_COUNT = 10;

function Person(name) {
  this.name = name;
}

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

// good
var $body = $("body");
複製代碼

變量聲明

一個函數做用域中全部的變量聲明儘可能提到函數首部。若是可使用 let 和 const 的，要使用 let 和 const。

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

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

單行長度

不要超過 100，但若是編輯器開啓 word wrap 能夠不考慮單行長度。

分號

統一要加分號。

空格

如下幾種狀況不用寫空格：

對象的屬性名後
函數調用括號前
不管是函數聲明仍是函數表達式，'('前不要空格
數組的'['後和']'前
運算符'('後和')'前

如下幾種狀況必定要寫空格：

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

這些後續會用 eslint 和 prettier 進行格式化

例：

// 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];

// good
var doSomething = function(a, b, c) {
  // do something
};

// good
doSomething(item);

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

// good
for (let i = 0; i < 6; i++) {
  x++;
}
複製代碼

空行

如下幾種狀況必定要有空行

變量聲明後（當變量聲明在代碼塊的最後一行時，則無需空行）
註釋前（當註釋在代碼塊的第一行時，則無需空行）
文件最後保留一個空行

var x = 1;

// 註釋前要有空行
if (x >= 1) {
  var y = x + 1;
}
複製代碼

換行

換行的地方，行末必須有','或者運算符；

如下幾種狀況不須要換行：

下列關鍵字後：else, catch, finally
代碼塊'{'前

如下幾種狀況須要換行：

代碼塊'{'後和'}'前
變量賦值後

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

x = y
    ? 1 : 2;

// good
var a = {
    b: 1,
    c: 2
};

x = y ? 1 : 2;

// good
if (condition) {
    ...
} else {
    ...
}

try {
    ...
} catch (e) {
    ...
} finally {
    ...
}

// not good
function test() {
    ...
}

// good
function test() {
    ...
}

// not good
var a, foo = 7, b,
    c, bar = 8;

// good
var a,
    foo = 7,
    b, c, bar = 8;
複製代碼

註釋

單行註釋

註釋單獨一行的狀況下，註釋的//後面要跟一個空格
註釋若是和代碼同一行，代碼分號結束後，要跟一個空格，註釋的//後也要跟一個空格

例：

// 調用函數
foo();

var maxCount = 10; // 這是一個變量
複製代碼

多行註釋

多行註釋使用下面這種形式：

/** * 代碼註釋1 * 代碼註釋2 */
複製代碼

多行註釋建議在如下幾種狀況使用：

難於理解的代碼段
可能存在錯誤的代碼段
瀏覽器特殊的 HACK 代碼
業務邏輯強相關的代碼

函數註釋

複雜的函數，全部類，都必須進行函數註釋，函數註釋使用業界統一的規範，方便後續使用 jsdoc 生成文檔。

例：

/** * 獲取任務的名稱 * @param id {Number} 傳入須要獲取名稱的人物id * @return {String} 返回的姓名 * @author shi 2015/07/21 能夠不寫 * @version 1.1.0 能夠不寫 * @example 示例代碼，能夠不寫 */
function getTaskName(id) {
  let name = "test";
  return name;
}
複製代碼

引號

最外層統一使用單引號，除非字符串嵌套的狀況。

// not good
var x = "test";

// good
var y = 'foo',
  z = '<div id="test"></div>';
複製代碼

對象，數組

對象屬性名不須要加引號，如對象屬性名是中劃線命名的須要加引號（eslint 的 rules）
對象以縮進的形式書寫，不要寫在一行（單個屬性能夠寫一行，es6 導入方法時可使用單行）；
數組、對象最後不要有逗號。

// good
var a = {
  b: 1,
  c: 2
};
複製代碼

括號

下列關鍵字後必須有大括號（即便代碼塊的內容只有一行）：if, else, for, while, do, switch, try, catch, finally, with。

// not good
if (condition) doSomething();

// good
if (condition) {
  doSomething();
}
複製代碼

undefined

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

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

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

// good
if (typeof person === 'undefined') {
    ...
}
複製代碼

不容許存在多層嵌套的條件判斷和循環（最多三層）

條件判斷能使用三目運算符和邏輯運算符解決的，就不要使用條件判斷，可是謹記不要寫太長的三目運算符。

例：

// bad
if (x === 10) {
  return 'valid';
} else {
  return 'invalid';
}

// good
return x === 10 ? 'valid' : 'invalid';

// bad
if (!x) {
  if (!y) {
    x = 1;
  } else {
    x = y;
  }
}

// good
x = x || y || 1;
複製代碼

簡單解釋一下邏輯運算符，邏輯運算符主要有兩種，一個是 || 邏輯或，一個是 && 邏輯與。

邏輯或 ||：當前一個爲真時，返回前一個值，前一個爲假時返回後一個值。

var x = 1;
console.log(x || 2); // 1

var y = 0;
console.log(y || 2); // 2
複製代碼

邏輯與 &&：當前一個爲真時，返回後一個值，前一個爲假時返回前一個值。

var x = 1;
console.log(x && 2); // 2

var y = 0;
console.log(y && 2); // 0
複製代碼

其餘 ESlint

for-in 裏必定要有 hasOwnProperty 的判斷；
不要在內置對象的原型上添加方法，如 Array, Date；
變量不要先使用後聲明；
不要在一句代碼中單單使用構造函數，記得將其賦值給某個變量；
不要在同個做用域下聲明同名變量；
不要在一些不須要的地方加括號，例：delete(a.b)；
不要使用未聲明的變量；
debugger 不要出如今提交的代碼裏；
數組中不要存在空元素；
不要在循環內部聲明函數；
不要直接 new 使用構造函數（new Vue() 除外）；
不要聲明瞭變量卻不使用；

這些均可以參考 eslint-config-alloy，有詳細的 JS、TS、React、Vue 的規範，咱們後續配置 eslint 時也是引入騰訊的 eslint 規範。

// good
for (key in obj) {
  if (obj.hasOwnProperty(key)) {
    // be sure that obj[key] belongs to the object and was not inherited
    console.log(obj[key]);
  }
}

// not good
Array.prototype.count = function(value) {
  return 4;
};

// not good
function test() {
  console.log(x);

  var x = 1;
}

// not good
new Person();

// good
var person = new Person();

// not good
delete (obj.attr);

// good
delete obj.attr;

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

// not good
var nums = [];

// not good
for (var i = 0; i < 10; i++) {
  (function(i) {
    nums[i] = function(j) {
      return i + j;
    };
  })(i);
}
複製代碼

其餘

換行符統一用'LF'；
對上下文 this 的引用只能使用'_this', 'that', 'self'其中一個來命名；
行尾不要有空白字符；
不容許有空的代碼塊（若是實在須要，能夠在代碼塊中寫註釋）。

// not good
function Person() {
  // not good
  var me = this;

  // good
  var _this = this;

  // good
  var that = this;

  // good
  var self = this;
}

if (condition) {
}
複製代碼