WEB Coding Conventions
前言
Any violation to this guide is allowed if it enhances readability.
在软件的生命周期里，一段代码可能会被许多人阅读或修改。如果一个代码可以清晰的展现出它的结构和特征，那就能减少在以后对其进行修改时出错的可能性。
编程规范可以帮助程序员们增加程序的健壮性。所有的WEB代码都是暴露给公众的。所以我们更应该保证其质量和可读性。
1. JSP Coding Conventions
请参考SUN Developer Network (SDN) 上的JSP开发规范。
http://java.sun.com/developer/technicalArticles/javaserverpages/code_convention/
2. HTML Coding Conventions
2.1 使用小写的HTML标签和属性标签
Eg:
<table></table>
<form name=”xxxx1” action=”xxxx.do”></form>
2.2 为HTML元素指定可用且表示实际意义的name属性和ID属性
Eg:
使用 txtName, txtAge 替换 text1, text2
2.3 保持合理的代码缩进
Eg:
<body>
<form name="frmActivity" method="post" action="xxx.do">
<input type="hidden" name="sqlState" value="" />
<input type="hidden" name="delState" value="" />
<input type="hidden" name="activityId" value="" />
<label for="cmbProjectId"></label>
<select name="cmbProjectId">
<option value="value1">value1</option>
</select>
</form>
</body>
2.4 单行代码的最大长度
单行代码最大长度为120个字符，超出部分予以折行处理。这有利于代码的可读性。 Eg:
<div id ="addActivityLayer">
<img onClick="form.submit();"
onMouseOut="this.src='../themes/beyondT/pictures/btn_save.gif';"
onMouseOver="this.src='../themes/beyondT/pictures/btn_save_1.gif';"
src="../../themes/beyondT/pictures/btn_save.gif" />
</div>
2.5 慎用HTML代码注释
HTML注释虽然不会在浏览器端有所展现，但会增加网络开销。因此HTML代码里面慎用注释，使用合理的name属性和ID属性以提高程序的可读性。
2.6 慎用 inline style 属性的使用
可能的情况下，尽量使用CSS class 代替 inline style 的使用，优点如下
l UI 风格有更好的协调性和一致性
l 更高的代码重用率，更好的可维护性。仅通过修改CSS可改变UI视角风格
2.7 使用外部CSS文件代替HTML代码中的style标签及内容
理由同2.6
2.8 从CSS里面引用图片
可能的情况下，尽量从CSS里引用图片而不是在HTML代码中直接使用图片。
以下内容，强制执行
2.9 XHTML1.0 规范有效验证
2.9.1 Document type
至少需要此document type, 可使用更为严格的限制
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
2.9.2 所有的标记都必须要有一个相应的结束标记
l 单标签：如果是单独不成对的标签，在标签最后加一个 "/" 来关闭它
Eg:
<br />
<img height=”80” alt=”w01f studio” src=”../images/logo.gif” width=”200” />
l 双标签：如果是双标签，则标签应成对出现，必须有结束标签来关闭它。
Eg:
<p></p>
<div></div>
2.9.3 所有的标签必须合理嵌套
XHTML要求有严谨的结构，因此所有的嵌套都必须按顺序严格对称
Eg:
<p><b></p></b> 要改写为：<p><b></b></p>
2.9.4 注意标签属性和方法的大小写敏感
由于在XHTML和CSS中是大小写敏感的，因此要求所有的标签和属性名字都必须使用小写。例如：<BODY>必须写成<body>，也不要大小写混杂。
2.9.5 所有的属性必须用引号""括起来
Eg:
<img height=80 width=20 src=logo.jpg />
应改为：
<img height=”80” width=”20” src=”logo.jpg” />
特殊情况，如果需要在属性值里使用双引号，可使用单引号’’代替，或使用编码"来表示。
Eg：
alt=”hello, "w01fer"”,则显示为：hello, “w01fer”
2.9.6 HTML 中的URL上的特殊字符，一律用编码来表示
Eg：
l URL中的小于号（<），则必须编码为：<
l URL中的双引号（"），则必须编码为：＆quot;
l URL中的AND (&) ，则必须编码为: &
2.9.7 给所有的属性赋值, 若不确定初始值可不出现此属性，禁止空值类型初始值
Eg:
<td nowrap> 必须改为<td nowrap=”nowrap”>
<input type=”checkbox” checked /> 改为
<input type=”checkbox” checked=”check”/>
<img alt=”logo” src=””> 是不正确写法
2.9.8 给script标签 添加CDATA标记
在标记CDATA下，所有的标记、实体引用都被忽略，而被XML处理程序一视同仁地当做字符数据看待，CDATA的形式如下：
<![CDATA[文本内容]]>
由“<![CDATA["为开始标记，以“]]>”为结束标记，注意CDATA为大写。
HTML中的Javascript代码块应该如下格式
<script type="text/javascript">
//<![CDATA[
function test() {
}
//]]>
</script>
2.9.9 尽量根据W3C的规范说明和要求正确的使用标签及属性
Javascript Coding Conventions
参考Sun 的Java 编程规范做大量修改后得到此JavaScript编程规范
3.1 JavaScript文件
JavaScript 程序应独立保存在后缀名为 .js 的文件, .js文件放到页面的<head>标 签 中。
3.2 保持合理的代码缩进
建议缩进的单位为四个空格。可使用 Tab 键来缩进。虽然使用缩进会增加文件的 大小，但在局域网中几乎可以忽略，且在最小化过程中也可被消除掉。
3.3 单行代码长度
避免每行超过 120 个字符。当一条语句一行写不下时，请考虑折行。在运算符号， 最好逗号后换行。在运算符后换行可以减少因为复制粘贴产生的错误被分号掩盖的 几率。
3.4 合理添加注释
l 注释应该和它所注释的代码一样是书写良好且清晰明了。要避免冗长或者情绪化。
l 及时地更新注释也很重要。错误的注释会让程序更加难以阅读和理解。
l 让注释有意义。重点在解释那些不容易立即明白的逻辑上。
l 使用单行注释。块注释用于注释正式文档和无用代码。
3.5 变量定义
3.5.1所有的变量必须在使用前进行定义。
虽然JavaScript 并不强制必须这么做，但如此声明有利于提高程序可读性。 且也容易发现那些没声明的变量(它们会被编译成全局变量)。
3.5.2 将变量定义语句放在函数/方法的首部。
JavaScript 没有块范围，所以在块里面定义变量很容易引起C/C++/Java 程 序员的误解。推荐首部定义所有的变量。
3.5.3 最好把每个变量的定义语句单独放到一行，并加上注释说明。
Eg:
var currentEntry; // 当前选择项
var level; // 缩进程度
var size; // 表格大小
3.5.4 尽量减少全局变量的使用。不要让局部变量覆盖全局变量。
3.6 函数/方法声明
3.6.1所有的函数/方法在使用前进行声明
内函数的声明跟在变量定义语句的后面。这样可以帮助判断哪些变量是在函数 范围内的。
3.6.2 格式定义
函数名与“(”（左括号）之间不应该有空格。“)”（右括号）与开始程序体的“{” （左大括号）之间应插入一个空格。函数程序体应缩进四个空格。“}”（右大括 号）与声明函数的那一行代码头部对齐。
Eg:
function outer(c，d) {
var e = c * d;
function inner(a， b) {
return (e * a) + b;
}
return inner(0， 1);
}
下面这种书写方式可以在 JavaScript 中正常使用，因为在 JavaScript 中， 函数和对象的声明可以放到任何表达式允许的地方。且它让内联函数和混合结 构具有最好的可读性。
Eg:
function getElementsByClassName(className) {
var results = [];
walkTheDOM(document.body, function (node) {
var a; // array of class names
var c = node.className; // the node's classname
var i; // loop counter
// If the node has a class name, then split it into a list of simple //names.
// If any of them match the requested name, then append the node to //the set of results.
if (c) {
a = c.split(' ');
for (i = 0; i < a.length; i += 1) {
if (a[i] === className) {
results.push(node);
break;
}
}
}
});
return results;
}
如果函数是匿名函数，则在 function 和 “(”（左括号）之间应有一个空格。如 果省略了空格，否则会让人感觉函数名叫作 function。
Eg:
div.onclick = function (e) {
return false;
};
that = {
method: function () {
return this.datum;
},
datum: 0
};
3.7命名规则
l 变量名应由 26 个大小写字母（A..Z，a..z），10 个数字（0..9），和 “_”（下划线） 组成。避免使用国际化字符（如中文），因为它们不是在任何地方都可以被方便的阅读和理解。不要在命名中使用 “$”（美元符号）或者 “”（反斜杠）。
l 不要把 “_”（下划线）作为变量名的第一个字符。某些组织（DOJO的规范）用它来表示私有变量，但实际上 JavaScript 并没私有变量的功能，虽然如此也尽量避免使用这种容易让人误解的命名习惯。
l 大多数的变量名和方法命应以小写字母开头。
l 必须与 new 共同使用的构造函数名应以大写字母开头。当 new 被省略时 JavaScript 不会有任何编译错误或运行错误抛出。忘记加 new 时会让不好的事情发生（比如被当成一般的函数），所以大写构造函数名是避免这种情况发生的有效办法。
l 全局变量应该全部大写。JavaScript 没有宏或者常量，所以不会因此造成误会。
3.8 语句和格式
3.8.1 简单语句
每一行最多只包含一条语句。以“;” （分号）结尾。注意函数赋值或对象赋值语 句也是赋值语句，应该以分号结尾。
JavaScript 可以把任何表达式当作一条语句。这很容易隐藏一些错误，特别是误 加分号的错误。只有在赋值和调用时，表达式才应被当作一条单独的语句。
3.8.2 复合语句
l 复合语句是被包含在 “{ }”（大括号）的语句序列。
l 被括起的语句必须适量的缩进标记。
l “{”（左大括号）应在复合语句其实行的结尾处。
l “}”（右大括号）应与“{”（左大括号）的那一行的开头对齐。
l 大括号应该在所有复合语句中使用，即使只有一条语句，当它们是控制结构的一部分时，比如一个 if 或者 for 语句。这样做可以避免以后添加语句时造成的错误。
3.8.3 return 语句
一条有返回值的 return 语句不要使用“( )”（括号）来括住返回值。如果返回表 达式，则表达式应与 return 关键字在同一行，以避免误加分号错误。
3.8.4 if 语句
if 语句，格式如下：
if (condition){
statements;
}
if (condition) {
statements;
} else {
statements;
}
if (condition) {
statements;
} else if (condition) {
statements;
} else {
statements;
}
3.8.5 for 语句
格式如下：
for (initialization;condition; update) {
statements;
}
for (variable in object) if (filter) {
statements;
}
第一种形式的循环用于已经知道相关参数的数组循环。
第二种形式应用于对象中。Object 原型中的成员将会被包含在迭代器中。通过预 先定义 hasOwnProperty方法来区分真正的 object 成员是个不错方法：
for (variablein object) if (object.hasOwnProperty(variable)){
statements;
}
3.8.6 while/do while 语句
while 语句格式如下：
while (condition){
statements;
}
do while 语句格式如下:
do {
statements;
} while (condition);
不像别的复合语句，do 语句总是以 “;”（分号）结尾。
3.8.7 switch/case 语句
switch/case 格式如下:
switch (expression){
case expression:
statements;
default:
statements;
}
每个 case 与 switch 对齐。这可避免过分缩进。每一组 statements（除了default 应以 break，return，或者 throw 结尾），不要让它顺次往下执行。
3.8.8 try/catch 语句
try/catch语句格式如下：
try {
statements;
} catch (variable){
statements;
}
try {
statements;
} catch (variable){
statements;
} finally {
statements;
}
3.8.9 空格的使用
用空行来将逻辑相关的代码块分割开可以提高程序的可读性。空格应在以下情况时 使用：
l 跟在“(”（左括号）后面的关键字应被一个空格隔开。Eg: while (true) {
l 函数参数与“(”（左括号）之间不应该有空格。这能帮助区分关键字和函数调用。
l 所有的二元操作符，除了“.”（点） 和“(”（左括号）和 “[”（左方括号）应用空格将其与操作数隔开。
l 一元操作符与其操作数之间不应有空格，除非操作符是个单词，比如 typeof。
l 每个在控制部分，比如 for 语句中的 “;”（分号）后须跟一个空格。
l 每个 “,”（逗号）后应跟一个空格。
3.9 附加建议
3.9.1 {} 和[]
使用 {} 代替 new Object()。使用 [] 代替 new Array() 。
当成员名是一组有序的数字时使用数组来保存数据。当成员名是无规律的字符串或 其他时使用对象来保存数据。
3.9.2（逗号）操作符
避免使用逗号操作符，除非在特定的 for 语句的控制部分。（这不包括那些被用在 对象定义，数组定义，变量定义语句，和参数列表中的逗号分隔符。）
3.9.3 作用域
在 JavaScript 中块没有域。只有函数有域。不要使用块，除非在复合语句中。
3.9.4 赋值表达式
避免在 if 和 while 语句的条件部分进行赋值。
if (a = b) {
是一条正确语句? 或者
if (a == b) {
才是对的? 避免这种不容易判断对错的结构。
3.9.5 === 和 !== 操作符
使用 === 和 !== 操作符会相对好点。== 和 != 操作符会进行类型强制转换。 特 别是，不要将 == 用于与错值比较（false，null，undefined，“”，0，NaN）。
3.9.6 令人迷惑的加号和减号
小心在 + 后紧跟 + 或 ++。这种形式很容易仍人迷惑。应插入括号以便于理解。
total = subtotal + +myInput.value;
最好能写成
total = subtotal + (+myInput.value);
这样 + + 不会被误认为是 ++。
3.9.7 Others
l eval 是 JavaScript 中最容易被滥用的方法。避免使用它。
l 不要使用 function 构造器。
l 不要给 setTimeout 或者 setInterval 传递字符串参数。
3342
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
