Seajs簡介

SeaJS是一個遵循CommonJS規范的JavaScript模塊加載框架，可以實現JavaScript的模塊化開發及加載機制。與jQuery等 JavaScript框架不同，SeaJS不會擴展封裝語言特性，而只是實現JavaScript的模塊化及按模塊加載。SeaJS的主要目的是令 JavaScript開發模塊化并可以輕松愉悅進行加載，將前端工程師從繁重的JavaScript文件及對象依賴處理中解放出來，可以專注于代碼本身的 邏輯。SeaJS可以與jQuery這類框架完美集成。使用SeaJS可以提高JavaScript代碼的可讀性和清晰度，解決目前JavaScript 編程中普遍存在的依賴關系混亂和代碼糾纏等問題，方便代碼的編寫和維護。

更多介紹請參考官方主頁：http://seajs.org/docs/。

目錄規范

代碼規范

模塊編寫

參照CMD規范。http://seajs.org/docs/#docs 文檔的模塊編寫規范。

命名規范

1. 必須使用 Tab 鍵進行代碼縮進，以節約代碼大小(建議設置編輯器的tab為4個空格的寬度)
2. 接口風格

1. 其他建議風格，非必要

1. 所有語句結束后，必須使用 ; 號結束
2. 所有變量必須是有意義的英文，嚴厲禁止拼音
3. 變量允許使用公認英文縮寫
4. 類命名必須是駝峰式
5. 常量必須所有單詞大寫，并且每個單詞間加下劃線
6. 枚舉類型時，枚舉的命名必須有意義，枚舉與枚舉成員必須以駝峰式
7. 常量和枚舉必須在最前端定義，merge 時注意，必須把常量與枚舉定義的文件放在文件列表的第一位
8. 變量內的簡寫單詞不能全大寫XmlDocument strHtml
9. "on"只能用作事件的命名
10. 函數開頭必須是有意義的動詞或動詞短語
11. 私有類的變量屬性成員 建議 使用混合式命名，并前面下下劃線
12. 臨時的全局變量放到一個全局的哈希表里，方便變量回收
13. 所有全局變量必須初始化，盡量少用全局變量
14. 大括號前面不能有換行符
15. 保留字以及特有的dom屬性不能作為變量名

特殊命名約定

1. 前面加 "is" 的變量名應該為布爾值，亦可使用 "can" "has" "should"
2. 前面加 "str" 的變量名應該為字符串
3. 前面加 "arr" 的變量名應該為數組
4. 前面加 "num" 或 "count" 的變量名應該為數字
5. "o" 作為局部變量或參數，表示為Object
6. "e" 作為局部變量或參數，表示為Element
7. "evt" 作為局部變量或參數，表示為event
8. "err" 作為局部變量或參數，表示為error
9. 重復變量建議使用 "i", "j", "k" （依次類推）等名稱的變量(全世界公認)
10. 能縮寫的單詞盡量縮寫
11. 避免產生令人誤解的布爾值 isNotNumber isNan
12. 處理錯誤的變量，必須在后面跟著 "Error"
13. 初始化用的函數 必須使用 "init" 開頭，如果一個頁面只有初始化可以單獨使用 init()
14. 盡量做有意義的代碼折行，不要讓一行代碼過長。(HTML 字符串除外)
15. 操作符 建議 使用空格隔開
16. 函數調用和方法 避免 使用空白
17. 逗號（,） 建議 使用空白隔開。
18. 不允許頻繁使用 previousSibling 和 nextSibling

詞法結構

1. 普通代碼段應該看起來如下：

   while(!isDone){
         doSomething();
         isDone = moreToDo();
   }

2. if 語句應該看起來像這樣：

   if(someCondition){
           statements;
   }elseif(someOtherCondition){
       statements;
   }else{
       statements;
   }

3. for 語句應該看起來像這樣：

   for(initialization; condition; update){
           statements;
   }

4. while 語句應該看起來像這樣：

   while(!isDone){
           doSomething();
       isDone = moreToDo();
   }

5. do ... while 語句應該看起來像這樣：

   do{
           statements;
   }while(condition);

6. switch 語句應該看起來像這樣：

   switch(condition){
   case ABC:
       statements;
       //  fallthrough
   case DEF:
       statements;
       break;
   default:
           statements;
       break;
   }

7. try ... catch 語句應該看起來像這樣：

   try{
       statements;
   }catch(ex){
       statements;
   }finally{
       statements;
   }

8. 單行的 if - else，while 或者 for 語句也必須加入括號：

   if(condition){ statement;}
   while(condition){ statement;}
   for(intialization; condition; update){ statement;}

注釋規范

具體的文檔示例可以參考 https://github.com/senchalabs/jsduck/wiki

• @author ：作者
• @class ：類
• @deprecated：標記此方法屬性或者類不贊成使用，在升級過渡的時候需兼容之前的API時特別有用。
• @example：給類或者方法添加一個代碼范例，jsduck不僅會給代碼著色，還能給代碼生成一個代碼編輯器，編輯代碼后可實時預覽，使用@example需要四個空格的縮進。
• @extends ：標記一個類繼承自另一個類，生成后會有一個類型繼承體系陳列在文檔視圖的右側。
• @cfg ：構造器的配置項，并在其后跟隨"{className}"，再跟隨參數名。

范例：@cfg {String} fieldName配置項的描述。

• @return ：與@cfg 類似，標記一個函數成員調用過后的返回類型。

范例：@return {Number} 文字描述

• @param：與@cfg 類似，給一個函數成員標記其所需的參數類型和描述，如果參數類型為多種可以用"/"分割，如需要給參數進行更詳細描述還能使用"[param.member]"描述符。

范例：@param {Number/String} fieldName

范例：@param {String[]} fieldName

范例： /**
* @cfg {Object} opt
* @cfg {Number} [opt.age]
* @cfg {Number} [opt.name=0]
*/

• @event ：標記一個事件，隨后通常會跟隨@param標簽給事件回調函數聲明參數的說明。
• @inheritdoc：在其后跟隨Class#member，常用在子類覆蓋父類成員后，子類注釋塊還需繼續使用父類注釋的情況下使用。
• @private ：將成員標記成私有，雖然也有@public 但如果不特殊標明即為公有。
• @protected ：將成員標記成受保護的。
• @static :將成員標記成靜態的，靜態成員也會在文檔中進行分類展示。
• @img ：在文檔注釋中鏈接一張圖片，讓文檔變得更具可讀性。
• @link ：在文檔注釋中標記某個類或類成員的錨點。

一個示例項目

該示例項目SVN : http://192.168.1.101:801/svn/998597/FrontProjectExample

環境配置

第一步：安裝文件下載

• Node.js http://nodejs.org/

第二步：執行安裝

$ npm install spm -g

$ npm install spm-chaos-build -g

關于 spm 和 spm-chaos-build的詳細介紹可以參考

https://github.com/spmjs/spm2

https://github.com/edokeh/spm-chaos-build

第三步：創建業務模塊

3.1：創建js文件

    在js/apps/test/目錄下創建module1.js內容為：

3.2：創建html文件

    在html/test/目錄下創建module1.html內容為:

    注意紅色框的修改（與js文件名和目錄一致）。

    預覽效果：

    此時要保證seajs-config.js的production配置屬性為flase,如下圖：

3.3：修改package.json

    修改js/apps目錄下的package.json，修改如下紅色框中的信息。

第四步：構建打包項目

    雙擊根目錄下的build.bat,可完成自動打包。

    查看seajs-config.js文件

    自動生成seajs的map

    預覽效果如下：

    請注意兩者之間的區別。    

總結

1. 為什么要使用seajs

管理開發和打包的有效的管理規范。

1. Require是異步加載的。

   相信看完下面兩篇文章，可以了解Require為什么是異步加載的了，如果你需要依賴加載的文件加載器，請選擇In.js: http://project.benben.cc/In/。

https://github.com/seajs/seajs/issues/259

https://github.com/seajs/seajs/issues/260

1. Export的輸出不能是函數返回值

https://github.com/seajs/seajs/issues/242

1. 外部js庫或樣式的調用方法

強烈建議使用In.js 在seajs.use之前把需要的JS庫加載進來，使用In.js主要有兩個原因

1. 能加載管理CSS文件
2. 加載CSS文件時不會出現多個css重復加載的問題（反面教材:DO.JS）

不建議使用庫中自帶的。Require模塊進行加載 在模塊中使用（do，labjs, in）進行加載，原因：

https://github.com/seajs/seajs/issues/993

1. 模塊內的js和css是自動打包的

   前文已經演示過，使用 pm-chaos-build 進行打包的過程，詳細請看：

   https://github.com/edokeh/spm-chaos-build-example

2. 按照注釋規范書寫，可以自動生成文檔。

   https://github.com/senchalabs/jsduck

   這是一個可以把你的代碼翻譯成.Extjs 文檔的好工具，但是前提要按照規則寫代碼。代碼規則

   https://github.com/senchalabs/jsduck/wiki/Guide

3. 測試是有必要的

        http://llying.iteye.com/blog/258605