碼上快樂

相關內容    簡體    繁體

前端開發規范與說明

本文轉載自   查看原文   2018-03-23 10:43   2567 

前端開發規范與說明

文中出現【強制】、【推薦】、【參考】標識規范等級，

一般規則

應用在 HTML, JavaScript 和 CSS上的通用規則。

  1. 文件、資源命名

    • 以可讀性而言，中划線用來分隔文件名
    • 確保文件命名總是以字母開頭而不是數字
    • 特殊含義的文件，需要對文件增加前后綴或特定的擴展名（比如 .min.js, .min.css），抑或一串前綴（比如 all.main.min.css）。使用點分隔符來區分這些在文件名中帶有清晰意義的元數據

  2. 文本縮進:一次縮進4個空格

  3. 代碼檢查

    • 對於前端JavaScript這種比較寬松自由的編程語言來說，嚴格遵循編碼規范和格式化風格指南極為重要。前端開發人員需嚴格遵循開發規范，並且使用自動代碼檢查工具（如JSHint）降低語法錯誤，確保代碼正確執行。JSHint是一款檢查JS代碼規范與否的工具，用來檢查JS代碼的規范性。它提供了配置的方法，來檢查不符合開發規范的錯誤

  4. 黃金定律

    • 永遠遵循同一套編碼規范 -- 可以是這里列出的，也可以是你自己總結的。如果你發現本規范中有任何錯誤，敬請指正。
    • 不管有多少人共同參與同一項目，一定要確保每一行代碼都像是同一個人編寫的。

HTML 規范

  1. 文檔類型 HTML5 docType

    使用 HTML5的文檔類型申明： <!DOCTYPE html>

    html5不基於SGML,因此不需要對DTD進行引用，但是需要doctype來規范瀏覽器的行為（讓瀏覽器按照他們應該的方式來運行）而HTML4.01基於SGML，所以需要對DTD進行引用，才能告知瀏覽器文檔所使用的文檔類型。

  2. media 標簽

    <meta name="viewport" content="width=device-width,initial-scale=1.0,maximum-scale=1.0,user-scalable=no">

         
     
     
             
              
      
      
      
&amp;amp;amp;lt;meta name="format-detection" content="telephone=no" /&amp;amp;amp;gt; // 禁止數字識自動別為電話號碼
&amp;amp;amp;lt;p&amp;amp;amp;gt;

    大部分 4.7~5 寸的安卓設備的 viewport 寬設為 360px，iPhone 6 上卻是 375px，大部分 5.5 寸安卓機器（比如說三星 Note）的 viewport 寬為 400，iPhone 6 plus 上是 414px。




  3. 語言屬性（Language attribute）


    強烈建議為 html 根元素指定 lang 屬性，從而為文檔設置正確的語言。這將有助於語音合成工具確定其所應該采用的發音，有助於翻譯工具確定其翻譯時所應遵守的規則等等。更多關於 lang 屬性的知識可以從 此規范 中了解。


    HTML 語言代碼參考手冊上的文章可以獲得更多有用的信息。




  4. 字符編碼


    通過明確聲明字符編碼，能夠確保瀏覽器快速並容易的判斷頁面內容的渲染方式。這樣做的好處是，可以避免在 HTML 中使用字符實體標記（character entity），從而全部與文檔編碼一致（一般采用 UTF-8 編碼）。




  5. 注釋


    
<!-- header  -->



    6. 	<li>
		<h3>引入CSS和JAVASCRIPT</h3>
		<p>【推薦】根據 HTML5 規范，在引入 CSS 和 JavaScript 文件時一般不需要指定 type 屬性，因為 text/css 和 text/javascript 分別是它們的默認值。</p>
	</li>
	<li>
		<h3>語法</h3>
		<p></p>
	</li>
	<li>
		<h3>屬性順序</h3>
		<p>【參考】HTML 屬性應當按照以下給出的順序依次排列，確保代碼的易讀性。</p>
		<ul>
			<li>class</li>
			<li>id, name</li>
			<li>data-*</li>
			<li>src, for, type, href</li>
			<li>title, alt</li>
			<li>aria-*, role</li>
		</ul>
		<p>【參考】class 用於標識高度可復用組件，因此應該排在首位。id 用於標識具體組件，應當謹慎使用（例如，頁面內的書簽），因此排在第二位。</p>
	</li>
	<li>
		<h3>語義化標簽</h3>
		<p>【推薦】根據元素（有時稱作“標簽”）其被創造出來時的初始意義來使用它,有根據有目的地使用 HTML 元素，對於可訪問性、代碼重用、代碼效率來說意義重大。</p>
	</li>
	<li>
		<h3>多媒體回溯:</h3>
		<p>【參考】對頁面上的媒體而言，像圖片、視頻、canvas 動畫等，要確保其有可替代的接入接口</p>
	</li>
	<li>
		<h3>關注點分離:</h3>
		<p>web 中的關注點包括信息（HTML 結構）、外觀（CSS）和行為（JavaScript）。為了使它們成為可維護的干凈整潔的代碼，必須將它們分離開。嚴格地保證結構、表現、行為三者分離，並使三者之間沒有太多的交互和聯系.就是說，盡量在文檔和模板中只包含結構性的 HTML；而將所有表現代碼，移入樣式表中；將所有動作行為，移入腳本中;在此之外，為使得它們之間的聯系盡可能的小，在文檔和模板中也盡量少地引入樣式和腳本文件</p>
		<ul>
			<li>【推薦】合並樣式，不引用過多樣式表</li>
			<li>【推薦】合並腳本，不使用過多腳本</li>
			<li>【推薦】不使用行內樣式</li>
			<li>【推薦】不在元素上使用style 屬性</li>
			<li>【推薦】不使用行內腳本</li>
			<li>【推薦】不使用表象元素</li>
			<li>【推薦】不使用表象 class 名（red, left, center）</li>
		</ul>
	</li>
	<li>
		<h3>type屬性</h3>
		<p>【推薦】省略樣式表與腳本上的 type 屬性。鑒於 HTML5 中以上兩者默認的 type 值就是 text/css 和text/javascript，所以 type 屬性一般是可以忽略掉的。在老舊版本的瀏覽器中這么做也是安全可靠的。</p>
	</li>
	<li>
		<h3>ID和錨點</h3>
		<p>【參考】在利用錨點提高用戶體驗方面，一個比較好的做法是將頁面內所有的頭部標題元素都加上 ID。頁面 URL 的 hash 中帶上對應的 ID 名稱，即形成描點，方便跳轉至對應元素所處位置。</p>
		<p>【參考】例如，在瀏覽器中輸入URL（帶有錨點）時，瀏覽器將定位至錨點對應元素位置。</p>
	</li>
	<li>
		<h3>HTML引號</h3>
		<p>【強制】使用雙引號(“”)而不是單引號(‘’)</p>
	</li>
	<li>
		<h3>實用為王</h3>
		<p>【推薦】盡量遵循 HTML 標准和語義，但是不要以犧牲實用性為代價。任何時候都要盡量使用最少的標簽並保持最小的復雜度。</p>
	</li>
</ol>

CSS 規范說明

文件規范

  1. 所有文件均歸檔至約定的目錄中：

  2. 框架引入方式

    • 外鏈引入方式
    • 整包導入項目方式

  3. 所有CSS分為兩大類：通用和業務類，通用的CSS文件放在如下目錄：

    • 基本樣式庫 CSS/core
    • 通用UI元素樣式庫/css/lib
    • JS組件相關樣式庫CSS/ui

  4. 業務類的CSS是指和具體產品相關的文件，放在如下目錄中：

    • 多模塊根據頁面模塊創建文件夾，
    • 只有一個模塊情況可以放入CSS文件夾

  5. 外聯CSS文件適用於全站級和產品通用的大文件，放入CSS/core

  6. 文件引入可通過外聯或內聯方式引入

  7. 文件名、文件編碼及文件大小

<h2>CSS注釋規范</h2>

<ol>
	<li>

【推薦】文件頂部注釋

/*
* @description:中文說明
* @author：name
* @update 2017-01-01 14:00
*/

  • 【推薦】模塊注釋：模塊注釋必須單獨寫在一行

    /* module: module2 by 張三 */
Codes
/* module: module2 by 張三 */

  • 【推薦】單行注釋與多行注釋,單行注釋可以寫在單獨一行，也可以寫在行尾，注釋中的每一行長度不超過40個漢字，或者80個英文字符。

  • 【推薦】特殊注釋：用於標注修改、待辦等信息

    /* TODO: xxxx by name 2013-04-13 18:32 */
Codes
/* BUGFIX: xxxx by name 2012-04-13 18:32 */

  • 【參考】區塊注釋

    /* Header */
/* Footer */
/* leftside */

    • <h2>CSS命名規范</h2>
<p>ID和class(類)名使用可以反應元素目的和用途的名稱，或其他通用名稱。使用具體且反映元素目的的名稱，這些是最容易理解的，而且發生變化的可能性最小。使用連字符（中划線）分隔命名中的單詞。為了增強課理解性，在選擇器中不要使用除了連字符（中划線）以為的任何字符（包括沒有）來連接單詞和縮寫。另外，作為該標准，預設屬性選擇器能識別連字符（中划線）作為單詞[attribute|=value]的分隔符。</p>
<ol>
	<li>【強制】盡可能提高代碼模塊的復用，樣式盡量用組合的方式</li>
	<li>【強制】命名避免使用中文拼音，應該采用更簡明有語義的英文單詞進行組合,應該用意義命名，而不是樣式顯示結果命名;不要用抽象的晦澀的命名.</li>
	<li>【強制】規則命名中，一律采用小寫加中划線的方式，不允許使用大寫字母或_、不允許通過1、2、3等序號進行命名</li>
	<li>【推薦】命名注意縮寫，但是不能盲目縮寫</li>
	<li>【推薦】ID命名要注意明確性及唯一性,不要隨意新建id</li>
	<li>【推薦】class命名要注意通用性及復用性,命名必須言簡意賅</li>
	<li>【推薦】避免class與id重名</li>
</ol>

<h2>聲明順序</h2>
<ol>
	<li>【參考】一，Positioning定位：可以使一個元素脫離正常文本流，並且覆蓋盒模型相關的樣式</li>
	<li>【參考】二，Box model 盒模型：決定了一個組件的大小和位置</li>
	<li>【參考】三，Typographic 排版：</li>
	<li>【參考】四，Visual 外觀：</li>
</ol>


<h2>CSS代碼格式</h2>
<ol>
	<li>
		<p>排版規范</p>
		<ul>
			<li>【強制】使用4個空格，而不使用tab或者混用空格+tab作為縮進</li>
			<li>【強制】規則可以寫成單行，或者多行，但是整個文件內的規則排版必須統一</li>
			<li>【強制】多個selector共用一個樣式集，則多個selector必須寫成多行形式 ；</li>
			<li>【強制】每一條規則結束的大括號 } 必須與規則選擇器的第一個字符對齊；</li>
			<li>【推薦】寫成單行時每一條規則的大括號 { 前后加空格，每一條規則結束的大括號 } 前加空格；</li>
			<li>【推薦】屬性名冒號之前不加空格，冒號之后加空格；</li>
			<li>【推薦】每一個屬性值后必須添加分號; 並且分號后空格；</li>
		</ul>
	</li>
	<li>
		<h3>規則書寫規范</h3>
		<ul>
			<li>【強制】使用單引號，不允許使用雙引號;</li>
			<li>【強制】除16進制顏色和字體設置外，CSS文件中的所有的代碼都應該小寫;</li>
			<li>【強制】除了重置瀏覽器默認樣式外，禁止直接為html tag添加css樣式設置;</li>
			<li>【強制】每一條規則應該確保選擇器唯一，禁止直接為全局.nav、.header、.body等類設置屬性;</li>
		</ul>
	</li>
	<li>
		<h3>代碼性能優化</h3>
		<ul>
			<li>【推薦】合並margin、padding、border的-left/-top/-right/-bottom的設置，盡量使用短名稱。</li>
			<li>【推薦】選擇器應該在滿足功能的基礎上盡量簡短，減少選擇器嵌套，查詢消耗。但是一定要避免覆蓋全局樣式設置。</li>
			<li>【推薦】注意選擇器的性能，不要使用低性能的選擇器。</li>
			<li>【推薦】禁止在css中使用*選擇符。</li>
			<li>【推薦】除非必須，否則，一般有class或id的，不需要再寫上元素對應的tag。</li>
			<li>【推薦】0后面不需要單位，比如0px可以省略成0，0.8px可以省略成.8px。</li>
			<li>【推薦】如果是16進制表示顏色，則顏色取值應該大寫，如果可以，顏色盡量用三位字符表示，例如#AABBCC寫成#ABC 。</li>
			<li>【推薦】如果沒有邊框時，不要寫成border:0，應該寫成border:none 。</li>
			<li>【推薦】盡量避免使用AlphaImageLoader </li>
			<li>【推薦】在保持代碼解耦的前提下，盡量合並重復的樣式。</li>
			<li>【推薦】background、font等可以縮寫的屬性，盡量使用縮寫形式 。</li>
		</ul>
	</li>
	<li>
		<h3>CSS Hack的使用</h3>
		<p>請不用動不動就使用瀏覽器檢測和CSS Hacks，先試試別的解決方法吧！考慮到代碼高效率和易管理，雖然這兩種方法能快速解決瀏覽器解析差異，但應被視為最后的手段。在長期的項目中，允許使用hack只會帶來更多的hack，你越是使用它，你越是會依賴它！ </p>
		<ul>
			<li>
				區別屬性：
				IE6 -- _property:value
				IE6/7 -- *property:value
				IE6/7/8/9 -- property:value\9
			</li>
			<li>
				區別規則：
				IE6 --  * html select {...}
				IE7 --  *:fist-child+html selector {...}
				非IE6 --  html&gt;body selector {...}
				firefox only --  @-moz-document url-prefix() {...}
			</li>
		</ul>
	</li>
	<li>
		<h3>字體規則</h3>
		<ul>
			<li>為了防止文件合並及編碼轉換時造成問題，建議將樣式中文字體名字改成對應的英文名字，如：黑體(SimHei) 宋體(SimSun) 微軟雅黑 (Microsoft Yahei，幾個單詞中間有空格組成的必須加引號) </li>
			<li>為了對font-family取值進行統一，更好的支持各個操作系統上各個瀏覽器的兼容性，font-family不允許在業務代碼中隨意設置</li>
		</ul>
	</li>
</ol>
<!-- <ol>
	<li>使用組合選擇器時，保持每個獨立的選擇器占用一行。</li>
	<li>為了代碼的易讀性，在每個聲明的左括號前增加一個空格。</li>
	<li>聲明塊的右括號應該另起一行。</li>
	<li>每條聲明 : 后應該插入一個空格。</li>
	<li>每條聲明應該只占用一行來保證錯誤報告更加准確。</li>
	<li>所有聲明應該以分號結尾。雖然最后一條聲明后的分號是可選的，但是如果沒有他，你的代碼會更容易出錯。</li>
	<li>逗號分隔的取值，都應該在逗號之后增加一個空格。比如說box-shadow</li>
	<li>不要在顏色值 rgb() rgba() hsl() hsla()和 rect() 中增加空格，並且不要帶有取值前面不必要的 0 (比如，使用 .5 替代 0.5)。</li>
	<li>所有的十六進制值都應該使用小寫字母，例如 #fff。因為小寫字母有更多樣的外形，在瀏覽文檔時，他們能夠更輕松的被區分開來。</li>
	<li>盡可能使用短的十六進制數值，例如使用 #fff 替代 #ffffff。</li>
	<li>為選擇器中的屬性取值添加引號，例如 input[type=”text”]。 他們只在某些情況下可有可無，所以都使用引號可以增加一致性。</li>
	<li>不要為 0 指明單位，比如使用 margin: 0; 而不是 margin: 0px;。 對這里提到的規則有問題嗎？參考 Wikipedia 中的 CSS 語法部分</li>
</ol> -->

<h2>CSS編碼技巧</h2>
<ol>
	<li>【參考】盡量減少代碼重復</li>
	<li>【參考】合理使用簡寫</li>
	<li>【參考】是否應該使用預處理器？</li>
	<li>【參考】層級(z-index)必須清晰明確，頁面彈窗、氣泡為最高級（最高級為999），不同彈窗氣泡之間可在三位數之間調整；普通區塊為10-90內10的倍數；區塊展開、彈出為當前父層級上個位增加，禁止層級間盲目攀比。</li>
</ol>
<h2>CSS 常用工具</h2>
<ol>
	<li>W3C CSS validator：http://jigsaw.w3.org/css-validator/</li>
	<li>CSS Lint：http://csslint.net/</li>
	<li>CSS Usage：https://addons.mozilla.org/en-us/firefox/addon/css-usage/</li>
</ol>

    JS 規范

    JS文件規范

    1. 文件編碼統一UTF-8

    2. 使用嚴格模式（use strict）編寫代碼:ECMAScript 5 引入嚴格模式('strict mode')概念。通過嚴格模式，在函數內部選擇進行較為嚴格的全局或局部的錯誤條件檢測，使用嚴格模式的好處是可以提早知道代碼中的存在的錯誤，及時捕獲一些可能導致編程錯誤的ECMAScript行為。在開發中使用嚴格模式能幫助我們早發現錯誤。設立"嚴格模式"的目的，主要有以下幾個：錯誤檢測、規范、效率、安全、面向未來.

      • 消除Javascript語法的一些不合理、不嚴謹之處，減少一些怪異行為;
      • 消除代碼運行的一些不安全之處，保證代碼運行的安全；
      • 提高編譯器效率，增加運行速度
      • 為未來新版本的Javascript做好鋪墊
    <h2>JS注釋規約</h2>
<ol>
	<li>【強制】類，類屬性，類方法使用/**內容*/格式，不得使用// xxx方式</li>
	<li>【強制】方法內部單行注釋，在被注釋語句上方另起一行，使用//注釋。方法內部多行注釋使用/* */注釋，注意與代碼對齊。</li>
	<li>【推薦】代碼修改同時，注釋也要進行相應修改，尤其是參數、返回值、核心邏輯等的修改。說明：代碼與注釋更新不同步，就像路網與導航軟件更新不同步一樣，如果導航軟件嚴重滯后，就失去了導航的意義。</li>
	<li>【參考】謹慎注釋掉代碼。在上方詳細說明，而不是簡單地注釋掉。如果無用，則刪除;說明：代碼被注釋掉有兩種可能性：1）后續會恢復此段代碼邏輯。2）永久不用。前者如果沒有備注信息，難以知曉注釋動機。后者建議直接刪掉（代碼倉庫保存了歷史代碼）。</li>
	<li>【參考】對於注釋的要求：
		<ul>
			<li>第一、能夠准確反應設計思想和代碼邏輯</li>
			<li>第二、能夠描述業務含義，使別的程序員能夠迅速了解到代碼背后的信息。完全沒有注釋的大段代碼對於閱讀者形同天書，注釋是給自己看的，即使隔很長時間，也能清晰理解當時的思路；注釋也是給繼任者看的，使其能夠快速接替自己的工作。</li>
		</ul>
	</li>
	<li>【參考】好的命名、代碼結構是自解釋的，注釋力求精簡准確、表達到位。避免出現注釋的一個極端：過多過濫的注釋，代碼的邏輯一旦修改，修改注釋是相當大的負擔</li>
	<li>【參考】特殊注釋標記，請注明標記人與標記時間。注意及時處理這些標記，通過標記掃描，經常清理此類標記。線上故障有時候就是來源於這些標記處的代碼。
		<ul>
			<li>待辦事宜（TODO）:（ 標記人，標記時間，[預計處理時間]） 表示需要實現，但目前還未實現的功能。</li>
			<li>錯誤，不能工作（FIXME）:（標記人，標記時間，[預計處理時間]） 在注釋中用FIXME標記某代碼是錯誤的，而且不能工作，需要及時糾正的情況。</li>
		</ul>
	</li>
</ol>

<h2>JS命名規范</h2>
<ol>
	<li>【強制】文件夾統一使用全小寫</li>
	<li>【強制】代碼中命名不能以下划線或美元符開始，也不能以下划線或美元符結束</li>
	<li>【強制】代碼中嚴禁使用拼音與英文混合的方式，更不允許直接使用中文方式。純拼音命名方式也要避免采用（國際通用的名稱可視為英文，如：taobao，alibaba等）</li>
	<li>【強制】類名使用UpperCamelCase風格</li>
	<li>【強制】方法名、參數名、成員變量、局部變量都統一使用lowerCamelCase風格，必須遵從駝峰形式 如：localValue，getMessage()</li>
	<li>【強制】常量命名全部大寫，單詞間用下划線隔開，力求語義表達完整清楚，不要嫌名字長</li>
	<li>【強制】杜絕完全不規范的縮寫，避免望文不知義</li>
	<li>【推薦】為了達到代碼自解釋的目標，任何定義編程元素在命名時使用盡量完整單詞組合來表達其意</li>
</ol>


<h2>JS代碼風格規范</h2>
<ol>
	<li>【強制】大括號使用約定:如果大括號內容為空則簡潔的寫成{}即可，不需要換行；如果非空代碼塊則：
		<ul>
			<li>左大括號前不換行</li>
			<li>左大括號后換行</li>
			<li>右大括號前換行</li>
			<li>右大括號后還有else等代碼則不換行</li>
		</ul>
	</li>
	<li>【強制】左小括號和字符之間不出現空格；同樣，右小括號和字符之間也不出現空格（見下例）</li>
	<li>【強制】if/for/while/switch/do等保留字與括號之間都必須加空格</li>
	<li>【強制】任何二目、三目運算符的左右兩邊都需要加一個空格；如：settings = settings ? settings : {}; if (a &amp;&amp; flag == 1) {}</li>
	<li>【強制】注釋的雙斜線與注釋內容之間有且僅有一個空格; 如：// 注釋內容，注意在//和注釋內容之間有一個空格</li>
	<li>【強制】單行字符數限不超過 120 個，超出需要換行，超出需要換行時遵循如下原則：
		<ul>
			<li>第二行相對第一行縮進4空格，從第三行開始，不再繼續縮進</li>
			<li>運算符與下文一起換行</li>
			<li>方法調用是，多個參數需要換行時，在逗號后進行</li>
			<li>在括號前不要換行</li>
		</ul>
	</li>
	<li>【強制】方法參數在定義和傳入是，多個參數逗號后面加空格;如：Function Sum(a, b, c){} Sum(1, 2, 3);</li>
</ol>

<h2>JS常量定義規范</h2>
<ol>
	<li>【強制】不允許任何魔法值（即未經定義的常量）直接出現在代碼中</li>
	<li>【推薦】不要使用一個常量類維護所有常量，按常量功能進行歸類，分開維護</li>
	<li>【推薦】常量復用層次，公共常量、模塊常量、功能頁面常量</li>
</ol>
<h2>JS控制語句規范</h2>
<ol>
	<li>【強制】在一個switch塊內，每個case要么通過break、return等來終止，要么注釋說明程序將繼續執行到哪一個case為止；在一個switch塊內，都必須包含一個default語句，並且放在最后，即是他什么代碼也沒有。</li>
	<li>【強制】在if/else/for/while/do語句中必須使用大括號。即使只有一行代碼，避免采用單行的編碼方式：if (condition) statements;</li>
	<li>【推薦】表達異常的分支時，少用if-else方式，這種方式可以改寫成，如果非得使用避免后續代碼維護困難，請勿超過3層。</li>
	<li>【推薦】不要在條件判斷中執行其它復雜的語句，將復雜邏輯判斷的結果賦值給一個有意義的布爾變量名，以提高可讀性（很多if語句內的邏輯相當復雜，閱讀者需要分析條件表達式的最終結果，才能明確什么樣的條件執行什么樣的語句，那么，如果閱讀者分析邏輯表達式錯誤呢？ ）</li>
	<li>【推薦】循環體中的語句要考量性能</li>
</ol>


    免責聲明！

    本站轉載的文章為個人學習借鑒使用，本站對版權不負任何法律責任。如果侵犯了您的隱私權益，請聯系本站郵箱yoyou2525@163.com刪除。



    猜您在找 前端開發規范-javascript規范 web前端開發規范 Web前端開發規范 Web前端開發規范之圖片命名規范 web前端開發代碼規范 《前端之路》 之 前端開發規范 從制定到實施 項目開發規范（編碼規范、命名規范、安全規范、前端優化、源碼提交規范、代碼維護規范、產品發布規范） 前端開發 css、less編寫規范 Web前端開發規范文檔 Web前端開發規范文檔
     
    粵ICP備18138465號   © 2018-2025 CODEPRJ.COM