JavaScript 開發規範

標籤：

　　本篇主要介紹JS的命名規範、注釋規範以及架構開發的一些問題。

目錄

1. 命名規範：介紹變數、函數、常量、建構函式、類的成員等等的命名規範

2. 注釋規範：介紹單行注釋、多行注釋以及函數注釋

3. 架構開發：介紹全域變數衝突、單全域變數以及命名空間

 

1. 命名規範駝峰式命名法介紹：

駝峰式命名法由小(大)寫字母開始，後續每個單詞首字母都大寫。

按照第一個字母是否大寫，分為：

① Pascal Case 大駝峰式命名法：首字母大寫。eg：StudentInfo、UserInfo、ProductInfo

② Camel Case 小駝峰式命名法：首字母小寫。eg：studentInfo、userInfo、productInfo

1.1 變數

命名方法：小駝峰式命名法。

命名規範：首碼應當是名詞。(函數的名字首碼為動詞，以此區分變數和函數)

命名建議：盡量在變數名字中體現所屬類型，如:length、count等表示數字類型；而包含name、title表示為字串類型。

樣本：

// 好的命名方式var maxCount = 10;var tableTitle = ‘LoginTable‘;// 不好的命名方式var setCount = 10;var getTitle = ‘LoginTable‘;

 

1.2 函數

命名方法：小駝峰式命名法。

命名規範：首碼應當為動詞。

命名建議：可使用常見動詞約定

動詞	含義	傳回值
can	判斷是否可執行某個動作(許可權)	函數返回一個布爾值。true：可執行；false：不可執行
has	判斷是否含有某個值	函數返回一個布爾值。true：含有此值；false：不含有此值
is	判斷是否為某個值	函數返回一個布爾值。true：為某個值；false：不為某個值
get	擷取某個值	函數返回一個非布爾值
set	設定某個值	無傳回值、返回是否設定成功或者返回鏈式對象
load	載入某些資料	無傳回值或者返回是否載入完成的結果

樣本：

// 是否可閱讀function canRead() {    return true;}// 擷取名稱function getName() {    return this.name;}

 

1.3 常量

命名方法：名稱全部大寫。

命名規範：使用大寫字母和底線來組合命名，底線用以分割單詞。

命名建議：無。

樣本：

var MAX_COUNT = 10;var URL = ‘http://www.baidu.com‘;

 

1.4 建構函式

介紹：在JS中，建構函式也屬於函數的一種，只不過採用new 運算子建立對象。

命名方法：大駝峰式命名法，首字母大寫。

命名規範：首碼為名稱。

命名建議：無。

樣本：

function Student(name) {    this.name = name;}var st = new Student(‘tom‘);

 

1.5 類的成員

類的成員包含：

① 公用屬性和方法：跟變數和函數的命名一樣。

② 私人屬性和方法：首碼為_(底線)，後面跟公用屬性和方法一樣的命名方式。

樣本：

function Student(name) {    var _name = name; // 私人成員    // 公用方法    this.getName = function () {        return _name;    }    // 公用方式    this.setName = function (value) {        _name = value;    }}var st = new Student(‘tom‘);st.setName(‘jerry‘);console.log(st.getName()); // => jerry：輸出_name私人變數的值

 

2. 注釋規範

JS支援兩種不同類型的注釋：單行注釋和多行注釋。

2.1 單行注釋

說明：單行注釋以兩個斜線開始，以行尾結束。

文法：// 這是單行注釋

使用方式：

① 單獨一行：//(雙斜線)與注釋文字之間保留一個空格。

② 在代碼後面添加註釋：//(雙斜線)與代碼之間保留一個空格，並且//(雙斜線)與注釋文字之間保留一個空格。

③ 注釋代碼：//(雙斜線)與代碼之間保留一個空格。

樣本：

// 調用了一個函數；1)單獨在一行setTitle();var maxCount = 10; // 設定最大量；2)在代碼後面注釋// setName(); // 3)注釋代碼

 

2.2 多行注釋

說明：以/*開頭，*/結尾

文法：/* 注釋說明 */

使用方法：

① 若開始(/*)和結束(*/)都在一行，推薦採用單行注釋。

② 若至少三行注釋時，第一行為/*，最後行為*/，其他行以*開始，並且注釋文字與*保留一個空格。

樣本：

/** 代碼執行到這裡後會調用setTitle()函數* setTitle()：設定title的值*/setTitle();

 

2.3 函數(方法)注釋

說明：函數(方法)注釋也是多行注釋的一種，但是包含了特殊的注釋要求，參照 javadoc(百度百科)。

文法：

/**
* 函數說明 
* @關鍵字 
*/

常用注釋關鍵字：(只列出一部分，並不是全部)

注釋名	文法	含義	樣本
@param	@param 參數名 {參數類型}  描述資訊	描述參數的資訊	@param name {String} 傳入名稱
@return	@return {傳回型別} 描述資訊	描述傳回值的資訊	@return {Boolean} true:可執行;false:不可執行
@author	@author 作者資訊 [附屬資訊：如郵箱、日期]	描述此函數作者的資訊	@author 張三 2015/07/21
@version	@version XX.XX.XX	描述此函數的版本號碼	@version 1.0.3
@example	@example 範例程式碼	示範函數的使用	@example setTitle(‘測試‘)

樣本：

/*** 合并Grid的行* @param grid {Ext.Grid.Panel} 需要合并的Grid* @param cols {Array} 需要合并列的Index(序號)數組；從0開始計數，序號也包含。* @param isAllSome {Boolean} ：是否2個tr的cols必須完成一樣才能進行合并。true：完成一樣；false(預設)：不完全一樣* @return void* @author polk6 2015/07/21  * @example* _________________                             _________________* |  年齡 |  姓名 |                             |  年齡 |  姓名 |* -----------------      mergeCells(grid,[0])   -----------------* |  18   |  張三 |              =>             |       |  張三 | * -----------------                             -  18   ---------* |  18   |  王五 |                             |       |  王五 |* -----------------                             -----------------*/function mergeCells(grid, cols, isAllSome) {// Do Something}

 

3. 架構開發3.1 全域變數衝突

　　在團隊開發或者引入第三方JS檔案時，有時會造成全域對象的名稱衝突，比如a.js有個全域函數sendMsg()，b.js也又有個全域函數sendMsg()，引入a.js和b.js檔案時，會造成sendMsg()函數衝突。

樣本：

 

 

3.2 單全域變數

　　所建立的全域對象名稱是獨一無二的，並將所有的功能代碼添加到這個全域對象上。調用自己所寫的代碼時，以這個全域對象為進入點。

如：

* JQuery的全域對象：$和JQuery

* ExtJS的全域對象： Ext

樣本：

 

3.3 命名空間

　　在項目規模日益壯大時，可採用命名空間方式對JS代碼進行規範：即將代碼按照功能進行分組，以組的形式附加到單全域對象上。

以Ext的chart模組為例：

 

==================================系列文章==========================================

本篇文章：3.10 JavaScript 開發規範

Web開發之路系列文章

 

JavaScript 開發規範