Seajs前端開發規範

時間 2019-11-10

標籤 seajs 前端開發規範简体版

原文原文鏈接

Seajs簡介

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

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

目錄規範

E:\WORKSPACES\MYECLIPSE10\FRONTPROJECTEXAMPLE\WEBROOT前端
│ build.batjava	自動打包壓縮的執行文件node
│jquery
├─htmlgit	存放前端展現頁面github
│ └─testweb
│ css.htmlnpm
│ test1.html
│
├─js	javascrpt 文件
│ │ cmd.bat
│ │ seajs-config.js	seajs配置文件
│ │ update.bat	更新seajs庫的可執行文件
│ │ update.rd
│ │
│ ├─apps	項目腳本文件
│ │ │ package.json	npm打包文件
│ │ │
│ │ ├─base	基礎公用的類方法
│ │ │ do.js
│ │ │ in.js
│ │ │ lab.js
│ │ │	業務目錄
│ │ └─test
│ │ 1.css
│ │ css.js
│ │
│ ├─otherlib	第三方腳本庫
│ │ │
│ │ └─jquery
│ │ ├─jquery
│ │ │ jquery-1.10.2.js
│ │ │ jquery-1.10.2.min.js
│ │ │
│ │ └─jquery-easyui-1.3.4
│ │
│ └─sea-modules	seajs庫
│ ├─apps	打包後的業務目錄文件
│ │
│ ├─gallery	自帶的經常使用庫
│ │ ├─handlebars
│ │ │ └─1.0.2
│ │ │ handlebars-debug.js
│ │ │ handlebars.js
│ │ │ package.json
│ │ │ runtime-debug.js
│ │ │ runtime.js
│ │ │
│ │ └─underscore
│ │ └─1.4.4
│ │ package.json
│ │ underscore-debug.js
│ │ underscore.js
│ │
│ ├─jquery
│ │ └─jquery
│ │ └─1.10.1
│ │ jquery-debug.js
│ │ jquery.js
│ │ package.json
│ │
│ └─seajs	seajs核心庫
│ ├─seajs
│ │ └─2.1.1
│ │ package.json
│ │ sea-debug.js
│ │ sea.js
│ │ sea.js.map
│ │
│ ├─seajs-style	樣式插件
│ │ └─1.0.2
│ │ package.json
│ │ seajs-style-debug.js
│ │ seajs-style.js
│ │
│ └─seajs-text	模版插件
│ └─1.0.3
│ package.json
│ seajs-text-debug.js
│ seajs-text.js
│
├─META-INF
│ MANIFEST.MF
│
└─WEB-INF
│ web.xml
│
├─classes
└─lib

代碼規範

模塊編寫

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

命名規範

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

結構	規則	例如
類	駝峯式	ModuleClass()
公有方法	混合式	getPosition()
公有變量	混合式	frameStyle
常量	大寫式	DEFAULT_FRAME_LAYOUT

其餘建議風格，非必要

結構	規則
私有方法	混合，例子：mixedCase
私有變量	混合，例子：mixedCase
方法（method）參數	混合，例子：mixedCase, mixedCase
本地（local）變量	混合，例子：mixedCase, mixedCase

全部語句結束後，必須使用 ; 號結束
全部變量必須是有意義的英文，嚴厲禁止拼音
變量容許使用公認英文縮寫
類命名必須是駝峯式
常量必須全部單詞大寫，而且每一個單詞間加下劃線
枚舉類型時，枚舉的命名必須有意義，枚舉與枚舉成員必須以駝峯式
常量和枚舉必須在最前端定義，merge 時注意，必須把常量與枚舉定義的文件放在文件列表的第一位
變量內的簡寫單詞不能全大寫XmlDocument strHtml
"on"只能用做事件的命名
函數開頭必須是有意義的動詞或動詞短語
私有類的變量屬性成員建議使用混合式命名，並前面下下劃線
臨時的全局變量放到一個全局的哈希表裏，方便變量回收
全部全局變量必須初始化，儘可能少用全局變量
大括號前面不能有換行符
保留字以及特有的dom屬性不能做爲變量名

特殊命名約定

前面加 "is" 的變量名應該爲布爾值，亦可以使用 "can" "has" "should"
前面加 "str" 的變量名應該爲字符串
前面加 "arr" 的變量名應該爲數組
前面加 "num" 或 "count" 的變量名應該爲數字
"o" 做爲局部變量或參數，表示爲Object
"e" 做爲局部變量或參數，表示爲Element
"evt" 做爲局部變量或參數，表示爲event
"err" 做爲局部變量或參數，表示爲error
重複變量建議使用 "i", "j", "k" （依次類推）等名稱的變量(全世界公認)
能縮寫的單詞儘可能縮寫
避免產生使人誤解的布爾值 isNotNumber isNan
處理錯誤的變量，必須在後面跟着 "Error"
初始化用的函數必須使用 "init" 開頭，若是一個頁面只有初始化能夠單獨使用 init()
儘可能作有意義的代碼折行，不要讓一行代碼過長。(HTML 字符串除外)
操做符建議使用空格隔開
函數調用和方法避免使用空白
逗號（,）建議使用空白隔開。
不容許頻繁使用 previousSibling 和 nextSibling

詞法結構

普通代碼段應該看起來以下：

while(!isDone){
doSomething();
isDone = moreToDo();
}
if 語句應該看起來像這樣：

if(someCondition){
statements;
}elseif(someOtherCondition){
statements;
}else{
statements;
}
for 語句應該看起來像這樣：

for(initialization; condition; update){
statements;
}
while 語句應該看起來像這樣：

while(!isDone){
doSomething();
isDone = moreToDo();
}
do ... while 語句應該看起來像這樣：

do{
statements;
}while(condition);
switch 語句應該看起來像這樣：

switch(condition){
case ABC:
statements;
  // fallthrough
case DEF:
statements;
  break;
default:
statements;
  break;
}
try ... catch 語句應該看起來像這樣：

try{
statements;
}catch(ex){
statements;
}finally{
statements;
}
單行的 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

預覽效果以下：

請注意二者之間的區別。

總結

爲何要使用seajs

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

Require是異步加載的。

相信看完下面兩篇文章，能夠了解Require爲何是異步加載的了，若是你須要依賴加載的文件加載器，請選擇In.js: http://project.benben.cc/In/。

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

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

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

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

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

強烈建議使用In.js 在seajs.use以前把須要的JS庫加載進來，使用In.js主要有兩個緣由

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

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

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

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

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

https://github.com/edokeh/spm-chaos-build-example
按照註釋規範書寫，能夠自動生成文檔。

https://github.com/senchalabs/jsduck

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

https://github.com/senchalabs/jsduck/wiki/Guide
測試是有必要的