js代码规范Word下载.docx
《js代码规范Word下载.docx》由会员分享,可在线阅读,更多相关《js代码规范Word下载.docx(26页珍藏版)》请在冰豆网上搜索。
6.10.with块语句18
第一章概述
规范制定原则
1方便代码的交流和维护。
2不影响编码的效率,不与大众习惯冲突。
3使代码更美观、阅读更方便。
4使代码的逻辑更清晰、更易于理解。
术语定义
Pascal大小写
将标识符的首字母和后面连接的每个单词的首字母都大写。
可以对三字符或更多字符的标识符使用Pascal大小写。
例如:
BackColor
Camel大小写
标识符的首字母小写,而每个后面连接的单词的首字母都大写。
backColor
文件命名组织
1.3.1文件命名
1文件名遵从Pascal命名法,无特殊情况,扩展名小写。
2使用统一而又通用的文件扩展名:
js文件.js
1.3.2文件注释
1在每个文件头必须包含以下注释说明
/*----------------------------------------------------------------
//文件名:
//文件功能描述:
//
//
//创建标识:
//修改标识:
//修改描述:
//----------------------------------------------------------------*/
文件功能描述只需简述,具体详情在类的注释中描述。
创建标识和修改标识由创建或修改人员的拼音或英文名加日期组成。
如:
黄小文20070408
一天内有多个修改的只需做一个在注释说明中做一个修改标识就够了。
在所有的代码修改处加上修改标识的注释。
第二章代码外观
2.1列宽
代码列宽控制在110字符左右。
2.2换行
当表达式超出或即将超出规定的列宽,遵循以下规则进行换行
1、在逗号后换行。
2、在操作符前换行。
3、规则1优先于规则2。
当以上规则会导致代码混乱的时候自己采取更灵活的换行规则。
2.3缩进
缩进应该是每行一个Tab(4个空格),不要在代码中使用Tab字符。
2.4空行
空行是为了将逻辑上相关联的代码分块,以便提高代码的可阅读性。
在以下情况下使用两个空行
1、类与类的定义之间。
在以下情况下使用一个空行
1、方法与方法、属性与属性之间。
2、方法中不同的逻辑块之间。
3、注释与它注释的语句间不空行,但与其他的语句间空一行。
2.5空格
在以下情况中要使用到空格
1、关键字和左括符“(”应该用空格隔开。
如
if(true)
注意在方法名和左括符“(”之间不要使用空格,这样有助于辨认代码中的方法调用与关键字。
2、多个参数用逗号隔开,每个逗号后都应加一个空格。
3、语句中的表达式之间用空格隔开。
for(expr1;
expr2;
expr3)
2.6括号-()
1、左括号“(”不要紧靠关键字,中间用一个空格隔开。
2、左括号“(”与方法名之间不要添加任何空格。
3、没有必要的话不要在返回语句中使用()。
if(condition)
Array.Remove
(1)
return1
2.7花括号-{}
1、左花括号“{”放于关键字或方法名的下一行并与之对齐。
{
}
functionAdd(x,y)
}
2、左花括号“{”要与相应的右花括号“}”对齐。
3、通常情况下左花括号“{”单独成行,不与任何语句并列一行。
4、if、while、do语句后一定要使用{},即使{}号中为空或只有一条语句。
if(somevalue==1)
somevalue=2;
5、右花括号“}”后建议加一个注释以便于方便的找到与之相应的{。
while
(1)
if(valid)
}//ifvalid
else
}//notvalid
}//endforever
第三章程序注释
3.1注释概述
1、修改代码时,总是使代码周围的注释保持最新。
2、在每个例程的开始,提供标准的注释样本以指示例程的用途、假设和限制很有帮助。
注释样本应该是解释它为什么存在和可以做什么的简短介绍.
3、避免在代码行的末尾添加注释;
行尾注释使代码更难阅读。
不过在批注变量声明时,行尾注释是合适的;
在这种情况下,将所有行尾注释在公共制表位处对齐。
4、避免杂乱的注释,如一整行星号。
而是应该使用空白将注释同代码分开。
5、避免在块注释的周围加上印刷框。
这样看起来可能很漂亮,但是难于维护。
6、在部署发布之前,移除所有临时或无关的注释,以避免在日后的维护工作中产生混乱。
7、如果需要用注释来解释复杂的代码节,请检查此代码以确定是否应该重写它。
尽一切可能不注释难以理解的代码,而应该重写它。
尽管一般不应该为了使代码更简单以便于人们使用而牺牲性能,但必须保持性能和可维护性之间的平衡。
8、在编写注释时使用完整的句子。
注释应该阐明代码,而不应该增加多义性。
9、在编写代码时就注释,因为以后很可能没有时间这样做。
另外,如果有机会复查已编写的代码,在今天看来很明显的东西六周以后或许就不明显了。
10、避免多余的或不适当的注释,如幽默的不主要的备注。
11、使用注释来解释代码的意图。
它们不应作为代码的联机翻译。
12、为了防止问题反复出现,对错误修复和解决方法代码总是使用注释,尤其是在团队环境中。
13、对由循环和逻辑分支组成的代码使用注释。
这些是帮助源代码读者的主要方面。
14、在整个应用程序中,使用具有一致的标点和结构的统一样式来构造注释。
15、用空白将注释同注释分隔符分开。
在没有颜色提示的情况下查看注释时,这样做会使注释很明显且容易被找到。
16、在所有的代码修改处加上修改标识的注释。
3.2文档型注释
该类注释采用.Net已定义好的Xml标签来标记,在声明类、方法、属性都应该使用该类注释,以便代码完成后直接生成代码文档,让别人更好的了解代码的实现和接口。
///<
summary>
设置HTTP标头。
<
/summary>
paramname="
p_name"
>
指定的标头名称。
/param>
p_value"
指定的标头值。
me.setHeader=function(p_name,p_value)
if(_headers==null)
_headers=newmw.utils.Dictionary();
_headers.set(p_name,p_value);
3.3类c注释
该类注释用于
1不再使用的代码。
2临时测试屏蔽某些代码。
用法
/*
[修改标识]
[修改原因]
...(thesourcecode)
*/
3.4单行注释
1方法内的代码注释。
如变量的声明、代码或代码段的解释。
注释示例:
//注释语句
varnumber;
2方法内变量的声明或花括号后的注释,注释示例:
if(1==1)//alwaystrue
{
statement;
}//alwaystrue
3.5注释标签
标签
用法
作用
c>
text<
/c>
text希望将其指示为代码的文本。
为您提供了一种将说明中的文本标记为代码的方法。
使用<
code>
将多行指示为代码
para>
content<
/para>
content段落文本。
用于诸如<
remarks>
或<
returns>
等标记内,使您得以将结构添加到文本中。
param>
paramname='
name'
description<
name为方法参数名。
将此名称用单引号括起来('
'
)。
应当用于方法声明的注释中,以描述方法的一个参数。
paramref>
paramrefname="
name"
/>
name
要引用的参数名。
将此名称用双引号括起来("
"
标记为您提供了一种指示词为参数的方法。
可以处理XML文件,从而用某种独特的方法格式化该参数。
see>
seecref="
member"
cref="
对可以通过当前编译环境进行调用的成员或字段的引用。
编译器检查到给定代码元素存在后,将member传递给输出XML中的元素名。
必须将member括在双引号("
)中。
使您得以从文本内指定链接。
seealso>
指示希望在“请参阅”一节中出现的文本。
seealsocref="
)中
使您得以指定希望在“请参阅”一节中出现的文本。
从文本
example>
/example>
description
代码示例的说明。
标记可以指定使用方法或其他库成员的示例。
一般情况下,这将涉及到<
标记的使用。
/code>
content为希望将其标记为代码的文本。
记为您提供了一种将多行指示为代码的方法。
指示应将说明中的文本标记为代码
此处description为对象的摘要。
应当用于描述类型成员。
以提供有关类型本身的信息。
exception>
exceptioncref="
/exception>
对可从当前编译环境中获取的异常的引用。
编译器检查到给定异常存在后,将member转换为输出XML中的规范化元素名。
description说明。
标记使您可以指定类能够引发的异常。
include>
includefile='
filename'
path='
tagpath[@name="
id"
]'
/>
filename包含文档的文件名。
该文件名可用路径加以限定。
将filename括在单引号中('
Tagpath:
filename中指向标记名的标记路径。
将此路径括在单引号中('
name注释前边的标记中的名称说明符;
名称具有一个id。
id
位于注释之前的标记的id。
将此id括在双引号中("
标记使您得以引用描述源代码中类型和成员的另一文件中的注释。
这是除了将文档注释直接置于源代码文件中之外的另一种可选方法。
标记使用XMLXPath语法。
有关自定义<
使用的方法,请参阅XPath文档。
list>
listtype="
bullet"
|"
number"
table"
<
listheader>
term>
term<
/term>
description>
/description>
/listheader>
item>
/item>
/list>
term定义的项,该项将在text中定义。
description目符号列表或编号列表中的项或者term的定义。
块用于定义表或定义列表中的标题行。
定义表时,只需为标题中的项提供一个项。
列表中的每一项用<
块指定。
创建定义列表时,既需要指定term也需要指定text。
但是,对于表、项目符号列表或编号列表,只需为text提供一个项。
列表或表所拥有的<
块数可以根据需要而定。
permission>
permissioncref="
/permission>
编译器检查到给定代码元素存在后,将member转换为输出XML中的规范化元素名。
description成员的访问的说明。
标记使您得以将成员的访问记入文档。
System.Security.PermissionSet使您得以指定对成员的访问。
/remarks>
description成员的说明。
标记是可以指定有关类或其他类型的概述信息的位置。
是可以描述该类型的成员的位置。
/returns>
description返回值的说明。
标记应当用于方法声明的注释,以描述返回值。
value>
property-description<
/value>
property-description属性的说明。
标记使您得以描述属性。
请注意,当在VisualStudio.NET开发环境中通过代码向导添加属性时,它将会为新属性添加<
标记。
然后,应该手动添加<
标记以描述该属性所表示的值。
第四章 申明
4.1每行声明数
一行只建议作一个声明,并按字母顺序排列。
varlevel;
//推荐
varsize;
varx,y;
//不推荐
4.2初始化
建议在变量声明时就对其做初始化。
4.3位置
变量建议置于块的开始处,不要总是在第一次使用它们的地方做声明。
functionmyMethod()
var_count=0;
//beginningofmethodblock
if(condition)
{
var_initCount=0;
//beginningof"
if"
block
...
}
不过也有一个例外
for(vari=0;
i<
maxLoops;
i++)
...
应避免不同层次间的变量重名,如
var_count;
functionmyMethod()
var_count=0;
//避免
}
第五章 命名规范
5.1命名概述
名称应该说明“什么”而不是“如何”。
通过避免使用公开基础实现(它们会发生改变)的名称,可以保留简化复杂性的抽象层。
例如,可以使用getNextStudent(),而不是getNextArrayElement()。
命名原则是:
选择正确名称时的困难可能表明需要进一步分析或定义项的目的。
使名称足够长以便有一定的意义,并且足够短以避免冗长。
唯一名称在编程上仅用于将各项区分开。
表现力强的名称是为了帮助人们阅读;
因此,提供人们可以理解的名称是有意义的。
不过,请确保选择的名称符合适用语言的规则和标准。
以下几点是推荐的命名方法。
1、避免容易被主观解释的难懂的名称,如方面名analyzeThis(),或者属性名xxK8。
这样的名称会导致多义性。
2、在类属性的名称中包含类名是多余的,如Book.bookTitle。
而是应该使用Book.title。
3、只要合适,在变量名的末尾或开头加计算限定符(Avg、Sum、Min、Max、Index)。
4、在变量名中使用互补对,如min/max、begin/end和open/close。
5、布尔变量名应该包含Is,这意味着Yes/No或True/False值,如fileIsFound。
6、在命名状态变量时,避免使用诸如Flag的术语。
状态变量不同于布尔变量的地方是它可以具有两个以上的可能值。
不是使用documentFlag,而是使用更具描述性的名称,如documentFormatType。
(此项只供参考)
5.2缩写
为了避免混淆和保证跨语言交互操作,请遵循有关区缩写的使用的下列规则:
1不要将缩写或缩略形式用作标识符名称的组成部分。
例如,使用getWindow,而不要使用getWin。
2不要使用计算机领域中未被普遍接受的缩写。
3在适当的时候,使用众所周知的缩写替换冗长的词组名称。
例如,用UI作为UserInterface缩
写,用OLAP作为On-lineAnalyticalProcessing的缩写。
4在使用缩写时,对于超过两个字符长度的缩写请使用Pascal大小写或Camel大小写。
例如,使用HtmlButton或HTMLButton。
但是,应当大写仅有两个字符的缩写,如,System.IO,而不是System.Io。
5不要在标识符或参数名称中使用缩写。
如果必须使用缩写,对于由多于两个字符所组成的缩写请
使用Camel大小写,虽然这和单词的标准缩写相冲突。
5.3表空间
1、全部使用小写
2、用名词或名词短语命名类
3、使用mw.分类.具体类名。
with($namespace("
mw.controls"
))
5.4类
1、使用Pascal大小写。
2、用名词或名词短语命名类。
3、使用全称避免缩写,除非缩写已是一种公认的约定,如URL、HTML
4、不要使用类型前缀,如在类名称上对类使用C前缀。
例如,使用类名称FileStream,而不是
CFileStream。
5、不要使用下划线字符(_)。
6、声明类时需带上表空间。
with($namespace("
mw.util"
表示键和值的集合。
mw.util.Dictionary=function()
varme=this;
获取包含在此字典中的键/值对的数目。
me.length=0;
var_internalDict=newActiveXObject("
scripting.dictionary"
);
var_values=newArray();
将指定的键和值添加到此字典中。
me.add=function(p_key,p_value)
_values.add(p_value);
_internalDict.add(p_key,p_value);
me.length=_values.length;
returnme;
5.5属性
1、使用Camel大小写。
3、约定:
内部受保护的属性使用下划线开头(_).
_cursor表示是受保护的属性,外界不应该使用。
mw.editors.CheckBox=function(p_container)
varme=newTextEditor(p_container,null);
me.editorType="
checkbox"
;
me._cursor="
default"
5.6参数
以下规则概述参数的命名指南:
1、使用描述性参数名称。
参数名称应当具有足够的描述性,以便参数的名称及其类型可用于在大多数情况下确定它的含义。
2、对参数名称使用Camel大小写。
3、以p_开头
以下是正确命名的参数的示例。
me.setValue=function(p_value)
me._value=p_value;
me._internalInput.checked=(me._value==me.params.valueChecked);
5.7方法
以下规则概述方法的命名指南:
1使用动词或动词短语命名方法。
2使用Camel大小写。
3约定:
类内部受保护的方法使用下划线开头(_).
setValue(p_value),_createInput
5.8事件
以下规则概述事件的命名指南:
1、对事件处理程序名称使用on开头。
2、事件处理程序都提供两个参数sender,args。
3、使用Before,After表示事件发