前言
良好的JavaScript書寫習慣的優點不言而喻,今天彬Go向大家推薦Dojo Javascript 編程規范,相當不錯的 Javascript 編程風格規范,建議大家可以借鑒一下此規范編寫 Javascript。感謝i.feelinglucky的翻譯。
序
Any violation to this guide is allowed if it enhances readability.
所有的代碼都要變成可供他人容易閱讀的。
快讀參考
核心 API 請使用下面的風格:
結構 規則 注釋 模塊 小寫 不要使用多重語義(Never multiple words) 類 駱駝 公有方法 混合 其他的外部調用也可以使用 lower_case(),這樣的風格 公有變量 混合 常量 駱駝 或 大寫
下面的雖然不是必要的,但建議使用:
結構 規則 私有方法 混合,例子:_mixedCase 私有變量 混合,例子:_mixedCase 方法(method)參數 混合,例子:_mixedCase, mixedCase 本地(local)變量 混合,例子:_mixedCase, mixedCase
命名規范
1.變量名稱 必須為 小寫字母。
2.類的命名使用駱駝命名規則,例如:
Account, EventHandler
3.常量 必須 在對象(類)或者枚舉變量的前部聲明。枚舉變量的命名必須要有實際的意義,並且其成員 必須 使用駱駝命名規則或使用大寫:
復制代碼 代碼如下:
var NodeTypes = {
Element : 1,
DOCUMENT: 2
}
4.簡寫單詞 不能使用 大寫名稱作為變量名:
getInnerHtml(), getXml(), XmlDocument
5.方法的命令 必須 為動詞或者是動詞短語:
obj.getSomeValue()
6.公有類的命名 必須 使用混合名稱(mixedCase)命名。
7.CSS 變量的命名 必須 使用其對應的相同的公共類變量。
8.私有類的變量屬性成員 必須 使用混合名稱(mixedCase)命名,並前面下下劃線(_)。例如:
復制代碼 代碼如下:
var MyClass = function(){
var _buffer;
this.doSomething = function(){
};
}
9.變量如果設置為私有,則前面 必須 添加下劃線。
this._somePrivateVariable = statement;
10.通用的變量 必須 使用與其名字一致的類型名稱:
setTopic(topic) // 變量 topic 為 Topic 類型的變量
11.所有的變量名 必須 使用英文名稱。
12.變量如有較廣的作用域(large scope),必須使用全局變量;此時可以設計成一個類的成員。相對的如作用域較小或為私有變量則使用簡潔的單詞命名。
13.如果變量有其隱含的返回值,則避免使用其相似的方法:
getHandler(); // 避免使用 getEventHandler()
14.公有變量必須清楚的表達其自身的屬性,避免字義含糊不清,例如:
MouseEventHandler
,而非 MseEvtHdlr。
請再次注意這條規定,這樣做得的好處是非常明顯的。它能明確的表達表達式所定義的含義。例如:
dojo.events.mouse.Handler // 而非 dojo.events.mouse.MouseEventHandler
15.類/構造函數 可以使用 擴展其基類的名稱命名,這樣可以正確、迅速的找到其基類的名稱:
EventHandler
UIEventHandler
MouseEventHandler
基類可以在明確描述其屬性的前提下,縮減其命名:
MouseEventHandler as opposed to MouseUIEventHandler.
特殊命名規范
術語 “get/set” 不要和一個字段相連,除非它被定義為私有變量。
前面加 “is” 的變量名 應該 為布爾值,同理可以為 “has”, “can” 或者 “should”。
術語 “compute” 作為變量名應為已經計算完成的變量。
術語 “find” 作為變量名應為已經查找完成的變量。
術語 “initialize” 或者 “init” 作為變量名應為已經實例化(初始化)完成的類或者其他類型的變量。
UI (用戶界面)控制變量應在名稱後加控制類型,例如: leftComboBox, TopScrollPane。
復數必須有其公共的名稱約定(原文:Plural form MUST be used to name collections)。
帶有 “num” 或者 “count” 開頭的變量名約定為數字(對象)。
重復變量建議使用 “i”, “j”, “k” (依次類推)等名稱的變量。
補充用語必須使用補充詞,例如: get/set, add/remove, create/destroy, start/stop, insert/delete, begin/end, etc.
能縮寫的名稱盡量使用縮寫。
避免產生歧義的布爾變量名稱,例如:
isNotError, isNotFound 為非法
錯誤類建議在變量名稱後加上 “Exception” 或者 “Error”。
方法如果返回一個類,則應該在名稱上說明返回什麼;如果是一個過程,則應該說明做了什麼。
文件
縮進請使用 4 個空白符的制表位。
如果您的編輯器支持 文件標簽_(file tags),請加添如下的一行使我們的代碼更容易閱讀:
// vim:ts=4:noet:tw=0:
譯注:老外用 VIM 編輯器比較多,此條可以選擇遵循。
代碼折疊必須看起來是完成並且是合乎邏輯的:
復制代碼 代碼如下:
var someExpression = Expression1
+ Expression2
+ Expression3;
var o = someObject.get(
Expression1,
Expression2,
Expression3
);
注:表達式的縮進與變量聲明應為一致的。
注:函數的參數應采用明確的縮進,縮進規則與其他塊保持一致。
變量
布局
塊
普通代碼段 應該 看起來如下:
復制代碼 代碼如下:
while (!isDone){
doSomething();
isDone = moreToDo();
}
IF 語句 應該 看起來像這樣:
復制代碼 代碼如下:
if (someCondition){
statements;
} else if (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; }
空白
注釋
文檔
下面提供了一些基本的函數或者對象的描述方法:
總結(summary): 簡短的表述此函數或者對象實現的目的
描述(description): 對於此函數或者類的簡短的描述
返回(return): 描述此函數返回什麼(並不包括返回類型)
基本函數信息
復制代碼 代碼如下:
function(){
// summary: Soon we will have enough treasure to rule all of New Jersey.
// description: Or we could just get a new roomate.
// Look, you go find him. He don't yell at you.
// All I ever try to do is make him smile and sing around
// him and dance around him and he just lays into me.
// He told me to get in the freezer 'cause there was a carnival in there.
// returns: Look, a Bananarama tape!
}
對象函數信息
沒有返回值描述
復制代碼 代碼如下:
{
// summary: Dingle, engage the rainbow machine!
// description:
// Tell you what, I wish I was--oh my g--that beam,
// coming up like that, the speed, you might wanna adjust that.
// It really did a number on my back, there. I mean, and I don't
// wanna say whiplash, just yet, cause that's a little too far,
// but, you're insured, right?
}
函數的聲明
在有的情況下,對於函數的調用和聲明是隱義(invisible)的。在這種情況下,我們沒有辦法在函數中加入說明等(供程序調用)。如果您遭遇了這種情況,您可以使用一個類來封裝函數。
注:此此方法只能在函數沒有初始化的參數情況下。如過不是,則它們會被忽略。
復制代碼 代碼如下:
dojo.declare(
"foo",
null,
{
// summary: Phew, this sure is relaxing, Frylock.
// description:
// Thousands of years ago, before the dawn of
// man as we knew him, there was Sir Santa of Claus: an
// ape-like creature making crude and pointless toys out
// of dino-bones, hurling them at chimp-like creatures with
// crinkled hands regardless of how they behaved the
// previous year.
// returns: Unless Carl pays tribute to the Elfin Elders in space.
}
);
<h3>參數</h3>
<ol>
<li>簡單類型
簡單的類型的參數可以直接在函數參數定義中注釋說明。
[cc lang="javascript"]function(/*String*/ foo, /*int*/ bar)...
可變類型參數
下面是幾個修飾符供參考:
? 可選參數
… 說面參數范圍不確定
數組
function(/*String?*/ foo, /*int...*/ bar, /*String[]*/ baz)...
全局參數描述
如果你想增加一個描述,你可以將它們移至初始化塊。
基本信息格式為: *關鍵字* 描述字段 ( *key* Descriptive sentence)
參數和變量的格式為: *關鍵字* ~*類型*~ 描述字段 ( *key* ~*type*~ Descriptive sentence)
注: *關鍵字* 和 ~*類型*~ 可以使用任何字母和數字表述。
復制代碼 代碼如下:
function (foo, bar) {
// foo: String
// used for being the first parameter
// bar: int
// used for being the second parameter
}
變量
由於實例變量、原型變量和外部變量的聲明是一致的,所以有很多的方法聲明、修改變量。具體的如何定義和定位應在變量最先出現的位置指明變量的名稱、類型、作用域等信息。
復制代碼 代碼如下:
function foo() {
// myString: String
// times: int
// How many times to print myString
// separator: String
// What to print out in between myString*
this.myString = "placeholder text";
this.times = 5;
}
foo.prototype.setString = function (myString) {
this.myString = myString;
}
foo.prototype.toString = function() {
for(int i = 0; i < this.times; i++) {
dojo.debug(this.myString);
dojo.debug(foo.separator);
}
}
foo.separator = "=====";
對象中的變量注釋
應使用和對象值和方法一致的標注方式,比如在他們聲明的時候:
復制代碼 代碼如下:
{
// key: String
// A simple value
key: "value",
// key2: String
// Another simple value
}
返回值
因為函數可以同時返回多個不同(類型)的值,所以應每個返回值之後加入返回類型的注釋。注釋在行內注釋即可,如果所有的返回值為同一類型,則指明返回的類型;如為多個不同的返回值,則標注返回類型為”mixed”。
復制代碼 代碼如下:
function() {
if (arguments.length) {
return "You passed argument(s)"; // String
} else {
return false; // Boolean
}
}
偽代碼(有待討論)
有時候您需要在函數或者類中添加對於此函數和類的功能性流程描述。如果您打算這樣做,您可以使用 /*======== (= 字符最好出現 5 次或者更多),這樣做的好處就是可以不用將這些東西加入代碼(譯注:原作者的意思可能為代碼管理系統)。
這樣看起來在 /*===== 和 =====*/ 會有非常長的一段注釋,等待功能調整完畢以後就可以考慮是否刪除。
復制代碼 代碼如下:
/*=====
module.pseudo.kwArgs = {
// url: String
// The location of the file
url: "",
// mimeType: String
// text/html, text/xml, etc
mimeType: ""
}
=====*/
function(/*module.pseudo.kwArgs*/ kwArgs){
dojo.debug(kwArgs.url);
dojo.debug(kwArgs.mimeType);
}
原文鏈接: http://dojotoolkit.org/developer/StyleGuide
翻譯(Translated by):i.feelinglucky{at}gmail.com from http://www.gracecode.com