前端編碼規(guī)范（1）

黃金屋1 2017-06-21

展開全文

這是一份旨在增強團隊的開發(fā)協(xié)作，提高代碼質量和打造開發(fā)基石的編碼風格規(guī)范,，其中包含了 HTML, JavaScript 和 CSS/SCSS 這幾個部分,。我們知道，當一個團隊開始指定并實行編碼規(guī)范的話,，錯誤就會變得更加顯而易見,。如果一段特定的代碼不符合規(guī)范的話，它有可能只是代碼風格錯誤,，而也有可能會是 bug,。早期指定規(guī)范就使得代碼審核得以更好的開展，并且可以更精確的地定位到錯誤,。只要開發(fā)者們能夠保證源代碼源文件都嚴格遵循規(guī)范,，那接下去所使用的混淆、壓縮和編譯工具則可投其所好不盡相同,。

一般規(guī)范

以下章節(jié)列舉了一些可應用在 HTML, JavaScript 和 CSS/SCSS 上的通用規(guī)則。

文件/資源命名

在 web 項目中,，所有的文件名應該都遵循同一命名約定,。以可讀性而言，減號（-）是用來分隔文件名的不二之選,。同時它也是常見的 URL 分隔符（i.e. ///blog/my-blog-entry or //s./images/big-black-background.jpg）,，所以理所當然的，減號應該也是用來分隔資源名稱的好選擇,。

請確保文件命名總是以字母開頭而不是數(shù)字,。而以特殊字符開頭命名的文件，一般都有特殊的含義與用處（比如 compass^[1] 中的下劃線就是用來標記跳過直接編譯的文件用的）,。

資源的字母名稱必須全為小寫,，這是因為在某些對大小寫字母敏感的操作系統(tǒng)中，當文件通過工具壓縮混淆后,，或者人為修改過后,，大小寫不同而導致引用文件不同的錯誤，很難被發(fā)現(xiàn),。

還有一些情況下,，需要對文件增加前后綴或特定的擴展名（比如 .min.js, .min.css），抑或一串前綴（比如 3fa89b.main.min.css）,。這種情況下,，建議使用點分隔符來區(qū)分這些在文件名中帶有清晰意義的元數(shù)據(jù),。

不推薦

html 代碼:
MyScript.js
myCamelCaseName.css
i_love_underscores.html
1001-scripts.js
my-file-min.css

推薦

html 代碼:
my-script.js
my-camel-case-name.css
i-love-underscores.html
thousand-and-one-scripts.js
my-file.min.css

協(xié)議

不要指定引入資源所帶的具體協(xié)議。

當引入圖片或其他媒體文件,，還有樣式和腳本時,，URLs 所指向的具體路徑，不要指定協(xié)議部分（http:, https:）,，除非這兩者協(xié)議都不可用,。

不指定協(xié)議使得 URL 從絕對的獲取路徑轉變?yōu)橄鄬Φ模谡埱筚Y源協(xié)議無法確定時非常好用,，而且還能為文件大小節(jié)省幾個字節(jié),。

不推薦

html 代碼:
<script src="http:///foundation.min.js"></script>

推薦

html 代碼:
<script src="http:///foundation.min.js"></script>

不推薦

css 代碼:
.example {
  background: url(http://static./images/bg.jpg);
}

推薦

css 代碼:
.example {
  background: url(//static./images/bg.jpg);
}

文本縮進

一次縮進兩個空格。

html 代碼:
<ul>
  <li>Fantastic</li>
  <li>Great</li>
  <li>
    <a href="#">Test</a>
  </li>
</ul>

css 代碼:
@media screen and (min-width: 1100px) {
  body {
    font-size: 100%;
  }
}

js 代碼:
(function(){
  var x = 10;
 
  function y(a, b) {
    return {
      result: (a + b) * x
    }
 
  }
}());

注釋

注釋是你自己與你的小伙伴們了解代碼寫法和目的的唯一途徑,。特別是在寫一些看似瑣碎的無關緊要的代碼時,，由于記憶點不深刻，注釋就變得尤為重要了,。

編寫自解釋代碼只是一個傳說,，沒有任何代碼是可以完全自解釋的。而代碼注釋,，則是永遠也不嫌多,。

當你寫注釋時一定要注意：不要寫你的代碼都干了些什么，而要寫你的代碼為什么要這么寫,，背后的考量是什么,。當然也可以加入所思考問題或是解決方案的鏈接地址。

不推薦

js 代碼:
var offset = 0;
 
if(includeLabels) {
  // Add offset of 20
  offset = 20;
}

推薦

js 代碼:
var offset = 0;
 
if(includeLabels) {
  // If the labels are included we need to have a minimum offset of 20 pixels
  // We need to set it explicitly because of the following bug: http:///issue-tracker/ISSUE-1
  offset = 20;
}

一些注釋工具可以幫助你寫出更好的注釋,。JSDoc 或 YUIDoc 就是用來寫 JavaScript 注釋用的,。你甚至可以使用工具來為這些注釋生成文檔，這也是激勵開發(fā)者們寫注釋的一個好方法,，因為一旦有了這樣方便的生成文檔的工具,，他們通常會開始花更多時間在注釋細節(jié)上。