開發規範（二）命名規範及註釋規範

概述

爲提升團隊協做效率，規範文件管理，方便項目後期維護，提升代碼質量，特制訂此文檔，前端開發人員必須遵守本規範進行前臺頁面開發。

命名規範

此規範爲圖片命名規範，html、css文件命名規範請參照 開發規範（一）目錄規範

圖片的名稱分爲頭尾兩部分，用減號-隔開，頭部分表示此圖片的大類性質

banner-* //放置在頁面頂部的廣告、裝飾圖案等長方形的圖片
logo-*   //標誌性的圖片
btn-*-*  //在頁面上位置不固定而且帶有連接的小圖片；命名規範：btn-功能名-大小/私有
pic-*    //裝飾用的照片
tit-*    //不帶連接表示標題的圖片
icon-*   //一系列圖標圖片

鼠標感應效果：圖片名+on/off；例如：icon-list-on.png,icon-list-off.png

文本縮進

（重要）統一使用 2 個空格縮進，不得使用 tab 和 4 個空格

註釋

重中之重，已加入績效考覈指標
更新代碼後即時更新註釋
註釋是你本身與你的小夥伴們瞭解代碼寫法和目的的惟一途徑。特別是在寫一些看似瑣碎的可有可無的代碼時，因爲記憶點不深入，註釋就變得尤其重要了。

當你寫註釋時必定要注意：不要寫你的代碼都幹了些什麼，而要寫你的代碼爲何要這麼寫，背後的考量是什麼。固然也能夠加入所思考問題或是解決方案的連接地址。

1. 在文件開始時寫塊註釋：

/** 
 * 做用於哪些頁面
 * 註明代碼業務/功能說明
 * @authors Your Name (you@example.org)
 * @date    2016-05-16
 * @version $Id$
 */

// 單行註釋添加一個空格

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;
}

模塊功能描述說明

/**
 * ------------------------------------------------------------------
 * 模塊描述說明
 * ------------------------------------------------------------------
 */

模塊內的小函數方法歸類：

/**
 * 小函數方法歸類說明，這些零散的小函數方法放在一塊兒 對應 一個業務方法邏輯
 * ------------------------------------------------------------------
 */

單個函數註釋

/**
 * 函數功能簡述
 *
 * 具體描述一些細節
 *
 * @param    {string}  address     地址
 * @param    {array}   com         商品數組
 * @param    {string}  pay_status  支付方式
 * @returns  void
 *
 * @date     2014-04-12
 * @author   QETHAN<qinbinyang@zuijiao.net>
 */

2. css註釋的寫法：

/* Footer */

內容區

/* End Footer */

關注點分離

理解 web 中如何和爲什麼區分不一樣的關注點，這很重要。這裏的關注點主要指的是：信息（HTML 結構）、外觀（CSS）和行爲（JavaScript）。爲了使它們成爲可維護的乾淨整潔的代碼，咱們要儘量的將它們分離開來。
嚴格地保證結構、表現、行爲三者分離，並儘可能使三者之間沒有太多的交互和聯繫。
就是說，儘可能在文檔和模板中只包含結構性的 HTML；而將全部表現代碼，移入樣式表中；將全部動做行爲，移入腳本之中。
在此以外，爲使得它們之間的聯繫儘量的小，在文檔和模板中也儘可能少地引入樣式和腳本文件。
清晰的分層意味着：
不使用超過一到兩張樣式表i.e. main.css, vendor.css
不使用超過一到兩個腳本（學會用合併腳本）
不使用行內樣式<style>.no-good {}</style>
不在元素上使用 style 屬性<hr style="border-top: 5px solid black">
不使用行內腳本<script>alert('no good')</script>
不使用表象元素i.e. <b>, <u>, <center>, <font>, <b>
不使用表象 class 名red, left, center

部份內容來自：強迫症->js註釋規範