這是一份旨在增強(qiáng)團(tuán)隊(duì)的開(kāi)發(fā)協(xié)作,提高代碼質(zhì)量和打造開(kāi)發(fā)基石的編碼風(fēng)格規(guī)范,其中包含了 HTML, JavaScript 和 CSS/SCSS 這幾個(gè)部分。我們知道,當(dāng)一個(gè)團(tuán)隊(duì)開(kāi)始指定并實(shí)行編碼規(guī)范的話,錯(cuò)誤就會(huì)變得更加顯而易見(jiàn)。如果一段特定的代碼不符合規(guī)范的話,它有可能只是代碼風(fēng)格錯(cuò)誤,而也有可能會(huì)是 bug。早期指定規(guī)范就使得代碼審核得以更好的開(kāi)展,并且可以更精確的地定位到錯(cuò)誤。只要開(kāi)發(fā)者們能夠保證源代碼源文件都嚴(yán)格遵循規(guī)范,那接下去所使用的混淆、壓縮和編譯工具則可投其所好不盡相同。
一般規(guī)范
以下章節(jié)列舉了一些可應(yīng)用在 HTML, JavaScript 和 CSS/SCSS 上的通用規(guī)則。
文件/資源命名
在 web 項(xiàng)目中,所有的文件名應(yīng)該都遵循同一命名約定。以可讀性而言,減號(hào)(-)是用來(lái)分隔文件名的不二之選。同時(shí)它也是常見(jiàn)的 URL 分隔符(i.e. //example.com/blog/my-blog-entry or //s.example.com/images/big-black-background.jpg),所以理所當(dāng)然的,減號(hào)應(yīng)該也是用來(lái)分隔資源名稱的好選擇。
請(qǐng)確保文件命名總是以字母開(kāi)頭而不是數(shù)字。而以特殊字符開(kāi)頭命名的文件,一般都有特殊的含義與用處(比如 compass[1] 中的下劃線就是用來(lái)標(biāo)記跳過(guò)直接編譯的文件用的)。
資源的字母名稱必須全為小寫(xiě),這是因?yàn)樵谀承⿲?duì)大小寫(xiě)字母敏感的操作系統(tǒng)中,當(dāng)文件通過(guò)工具壓縮混淆后,或者人為修改過(guò)后,大小寫(xiě)不同而導(dǎo)致引用文件不同的錯(cuò)誤,很難被發(fā)現(xiàn)。
還有一些情況下,需要對(duì)文件增加前后綴或特定的擴(kuò)展名(比如 .min.js, .min.css),抑或一串前綴(比如 3fa89b.main.min.css)。這種情況下,建議使用點(diǎn)分隔符來(lái)區(qū)分這些在文件名中帶有清晰意義的元數(shù)據(jù)。
不推薦
- MyScript.js
- myCamelCaseName.css
- i_love_underscores.html
- 1001-scripts.js
- my-file-min.css
推薦
- my-script.js
- my-camel-case-name.css
- i-love-underscores.html
- thousand-and-one-scripts.js
- my-file.min.css
協(xié)議
不要指定引入資源所帶的具體協(xié)議。
當(dāng)引入圖片或其他媒體文件,還有樣式和腳本時(shí),URLs 所指向的具體路徑,不要指定協(xié)議部分(http:, https:),除非這兩者協(xié)議都不可用。
不指定協(xié)議使得 URL 從絕對(duì)的獲取路徑轉(zhuǎn)變?yōu)橄鄬?duì)的,在請(qǐng)求資源協(xié)議無(wú)法確定時(shí)非常好用,而且還能為文件大小節(jié)省幾個(gè)字節(jié)。
不推薦
- <script src="http://cdn.com/foundation.min.js"></script>
推薦
- <script src="//cdn.com/foundation.min.js"></script>
不推薦
- .example {
- background: url(http://static.example.com/images/bg.jpg);
- }
推薦
- .example {
- background: url(//static.example.com/images/bg.jpg);
- }
文本縮進(jìn)
一次縮進(jìn)兩個(gè)空格。
- <ul>
- <li>Fantastic</li>
- <li>Great</li>
- <li>
- <a href="#">Test</a>
- </li>
- </ul>
- @media screen and (min-width: 1100px) {
- body {
- font-size: 100%;
- }
- }
- (function(){
- var x = 10;
- function y(a, b) {
- return {
- result: (a + b) * x
- }
- }
- }());
注釋
注釋是你自己與你的小伙伴們了解代碼寫(xiě)法和目的的唯一途徑。特別是在寫(xiě)一些看似瑣碎的無(wú)關(guān)緊要的代碼時(shí),由于記憶點(diǎn)不深刻,注釋就變得尤為重要了。
編寫(xiě)自解釋代碼只是一個(gè)傳說(shuō),沒(méi)有任何代碼是可以完全自解釋的。而代碼注釋,則是永遠(yuǎn)也不嫌多。
當(dāng)你寫(xiě)注釋時(shí)一定要注意:不要寫(xiě)你的代碼都干了些什么,而要寫(xiě)你的代碼為什么要這么寫(xiě),背后的考量是什么。當(dāng)然也可以加入所思考問(wèn)題或是解決方案的鏈接地址。
不推薦
- var offset = 0;
- if(includeLabels) {
- // Add offset of 20
- offset = 20;
- }
推薦
- 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://somebrowservendor.com/issue-tracker/ISSUE-1
- offset = 20;
- }
一些注釋工具可以幫助你寫(xiě)出更好的注釋。JSDoc 或 YUIDoc 就是用來(lái)寫(xiě) JavaScript 注釋用的。你甚至可以使用工具來(lái)為這些注釋生成文檔,這也是激勵(lì)開(kāi)發(fā)者們寫(xiě)注釋的一個(gè)好方法,因?yàn)橐坏┯辛诉@樣方便的生成文檔的工具,他們通常會(huì)開(kāi)始花更多時(shí)間在注釋細(xì)節(jié)上。
代碼檢查
對(duì)于比較寬松自由的編程語(yǔ)言來(lái)說(shuō),嚴(yán)格遵循編碼規(guī)范和格式化風(fēng)格指南就顯得極為重要。遵循規(guī)范固然很好,但是有自動(dòng)化流程來(lái)確保其執(zhí)行情況,豈不更佳。Trust is good, control is better.
對(duì)于 JavaScript,建議使用 JSLint 或 JSHint。
[1]: Compass 是一個(gè)基于 Sass 開(kāi)源的 CSS 框架,而 Sass 是一個(gè)非常流行的 CSS 預(yù)編譯器。