Web前端开发规范文档

作者: 喵呜君 | 来源:发表于2016-11-30 17:17 被阅读0次

基本准则

符合web标准，html语义化；

html，css，JavaScript分离；

代码简洁有序，尽可能减少冗余代码，降低服务器的负载；

解决pc端各浏览器的兼容性问题，处理移动端各设备适配问题。

通用规范

用四个空格代替TAB键

因为在不同系统的编辑工具对`tab`解析不一样，`windows`下的`tab`键是占四个空格的位置，而在`linux`下会变成占八个空格的位置（除非你自己设定了tab键所占的位置长度）。

如sublime text，可在这里对`tab`进行设置

![alt text](http://imglf0.ph.126.net/E0E8CvNB_YvjIzS972wZ2w==/6608627832887488476.png?_=3831620 "sublime")

CSS样式属性或者JAVASCRIPT代码后加“;”方便压缩工具“断句”。

文件内容编码统一为UTF-8。

文件规范

文件名统一使用小写英文单词，多个单词用驼峰命名法，如不使用驼峰命名法，建议使用"-"而不是"_"。

一些浏览器会将还有这些词的作为广告拦截，文件命名、ID、CLASS等所有命名避免以下词汇：

`ad`、`ads`、`adv`、`banner`、`sponsor`、`gg`、`guangg`、`guanggao`等。

HTML书写规范

为每个HTML页面的第一行添加标准模式（standard mode）的是声明，确保在每个浏览器中拥有一致的展现。
<pre>
<code><!DOCTYPE html></code>
</pre>
文档类型声明统一为HTML5声明类型，编码统一为UTF-8。
<pre>
<code><meta charset="UTF-8"></code>
</pre>
<HEAD>中添加信息。
<pre>
<code>
<meta name="author" content="smile@kang.cool">//作者
<meta name="description" content="hello">//网页描述
<meta name="keywords" content="a,b,c">//关键字,“，”分隔
<meta http-equiv="expires" content="Wed, 26 Feb 1997 08：21：57 GMT">//设定网页的到期时间。一旦网页过期，必须到服务器上重新调阅
<meta http-equiv="Pragma" content="no-cache">//禁止浏览器从本地机的缓存中调阅页面内容
<meta http-equiv="Window-target" content="_top">//用来防止别人在框架里调用你的页面
<meta http-equiv="Refresh" content="5;URL=http://kahn1990.com/">//跳转页面，5指时间停留5秒网页搜索机器人向导。用来告诉搜索机器人哪些页面需要索引，哪些页面不需要索引
<meta name="robots" content="none">//content的参数有all,none,index,noindex,follow,nofollow，默认是all
<link rel="Shortcut Icon" href="favicon.ico">//收藏图标
<meta http-equiv="Cache-Control" content="no-cache, must-revalidate">//网页不会被缓存
<meta name="viewport" content="width=device-width,initial-scale=1.0">//如果是移动端项目，需加上。告诉浏览器识别设备窗口尺寸，并禁止缩放。
</code>
</pre>
IE支持通过特定的<meta>标签来确定绘制当前页面所采用的的IE版本。除非有强烈的特殊需求，否则最好是设置为edge mode，从而通知IE采用其所支持的最新的模式。
<pre>
<code><meta http-equiv="X-UA-Compatible" content="IE=Edge"></code>
</pre>

非特殊情况下CSS样式文件外链至head内，JavaScript文件外链至body底部。
<pre>

<code><!DOCTYPE html>
<html>
<head>
    <link rel="stylesheet" href="css/main.css">
</head>
<body>
    <!-- 逻辑代码 -->
    <!-- 逻辑代码底部 -->
    <script src="lib/jquery/jquery-2.1.1.min.js"></script>
</body>
</html></code>
</pre>

引入JavaScript库文件，文件名须包含库名称及版本号及是否为压缩版。
<pre>
<code>jQuery-1.11.3.min.js</code>
</pre>
引入JavaScript插件，文件名格式为库名称+.+插件名称。
<pre>
<code>jQuery.cookie.js</code>
</pre>

HTML属性应当按照以下给出的顺序依次排列，来确保代码的易读性。
<pre>
<code>class
id、name
data-*
src、for、type、href
title、alt
aria-*、role</code>
</pre>
编码均遵循XHTML标准;
标签、属性、属性命名由小写英文、数字和_组成，且所有标签必须闭合;
属性值必须用双引号"";
避免使用中文拼音，尽量简易并要求语义化。
<pre>
<code>CLASS --> n-head-title --> CLASS遵循小驼峰命名法(little camel-case)
ID --> nHeadTitle --> ID遵循名称+"-"
NAME --> nHeadTitle --> NAME属性命名遵循小驼峰命名法(little camel-case)
<div class="n-head-title" id="nHeadTitle" name="nHeadTitle"></div></code>
</pre>
当JavaScript获取单个元素时，通常使用document.getElementById来获取dom元素，document.getElementById兼容所有浏览器，但IE浏览器会混淆元素的ID和NAME属性，所以要区分ID和NAME的命名。
<pre>
<code><input type="text" name="text">
<div id="test"></div>
<button onclick="alert(document.getElementById('test').tagName)"></button>

<!-- ie6下为INPUT --></code>
</pre>

特殊符号应使用转义符。
<pre>
<code>< --> <
--> >
空格 --> </code>
</pre>

含有描述性表单元素(input,textarea)添加label。
<pre>
<code><p>
<label for="test">测试</label>
<input type="text" id="test"/>
</p></code>
</pre>

多用无兼容性问题的HTML内置标签。

比如`span`、`em`、`strong`、`optgroup`、`label`等，需要自定义`HTML`标签属性时，首先考虑是否存在已有的合适标签可替换，如果没有，可使用`data-`为前缀来添加自定义属性，避免使用其他命名方式。

语义化HTML。

尽可能减少<div>嵌套。

书写链接地址时避免重定向。
<pre>
<code>href="http://www.kahn1990.com/" //即在URL地址后面加"/"</code>
</pre>

HTML中对于属性的定义，确保全部使用双引号，绝对不要使用单引号。

CSS书写规范

CSS样式新建或修改尽量遵循以下原则：

1. 根据新建样式的适用范围分为三级：全站级、产品级、页面级
2. 尽量通过继承和层叠重用已有的样式。
3. 不要轻易改动全站级CSS。改动后，要经过全面测试。

CSS属性显示顺序：

1. 显示属性
2. 元素位置
3. 元素属性
4. 元素内容属性

`CSS`书写顺序

<pre>
<code>.header{
    /*显示属性*/
        display || visibility
        list-style
        position top || right || bottom || left
        z-index
        clear
        float
    /*自身属性*/
        width max-width || min-width
        height max-height || min-height
        overflow || clip
        margin
        padding
        outline
        border
        background
    /*文本属性*/
        color
        font
        text-overflow
        text-align
        text-indent
        line-height
        white-space
        vertical-align
        cursor
        content
        };
</code>
</pre>

兼容多个浏览器时，将标准属性写在底部。

<pre>
<code>-moz-border-radius:15px;/*Firefox*/
-webkit-border-radius:15px;/*Safari和Chrome*/
border-radius:15px;/*Opera 10.5+，以及使用了IE-CSS3的IE浏览器*//标准属性</code>
</pre>

使用选择器时，命名比较短的词汇或者缩写的不允许直接定义样式。
<pre>
<code>.hd,.bd,.td{};//如这些命名</code>
</pre>

可用上级节点进行限定。

<pre>
<code>.recommend-mod .hd</code>
</pre>

多选择器规则之间换行，即当样式针对多个选择器时每个选择器占一行。

<pre>
<code>button.btn,
input.btn,
input[type="button"]{...};</code>
</pre>

优化`CSS`选择器。

<pre>
<code>#header a { color:#fff; };/*CSS选择器是从右边到左边进行匹配*/</code>
</pre>

浏览器将检查整个文档中的所有链接和每个链接的父元素，并遍历文档树去查找ID为header的祖先元素，如果找不到header将追溯的文档的根节点，解决方法如下：

<pre>
<code>避免使用通配符和相邻兄弟选择符、子选择符、后代选择符、属性选择符等选择器
不要限定ID选择符，如div#header(提高权重除外)
不要限定类选择器，如ul.recommend(提高权重除外)
不要使用 ul li a 这样长的选择符
避免使用标签子选择符，如#header > li > a </code>
</pre>

使用z-index属性尽量让z-index的值不要超过150(全站级的除外)，页面中的元素内容的z-index不能超过10(模态框等模块除外，但不能超过150)，不允许直接使用(999~9999)之间的值。

尽量避免使用CSS Hack。

<pre>
<code>property:value;/*所有浏览器*/
+property:value;/*IE7*/
_property:value;/*IE6*/
*property:value;/*IE6/7*/
property:value;/*IE6/7/8/9,即所有IE浏览器*/</code>
</pre>

<pre>
<code>* html selector {...};/*IE6*/
*:first-child+html selector {...};/*IE7*/
html>body selector {...};/*非IE6*/
@-moz-document url-prefix() {...};/*firefox*/
@media all and (-webkit-min-device-pixel-ratio:0) {...};/*saf3+/chrome1+*/
@media all and (-webkit-min-device-pixel-ratio:10000),not all and (-webkit-min-device-pixel-ratio:0) {...};/*opera*/
@media screen and (max-device-width:480px) {...};/*iphone/mobile webkit*/</code>
</pre>

避免使用低效的选择器。

<pre>
<code>body > * {...};
ul > li > a {...};
#footer > h3 {...};
ul#top_blue_nav {...};
#searbar span.submit a {...};/*反面示例*/</code>
</pre>

六个不要三个避免一个使用。
<pre>
<code>不要在标签上直接写样式

不要在CSS中使用expression
不要在CSS中使用@import
不要在CSS中使用“*”选择符
不要在CSS中使用！important
不要将CSS样式单行书写
避免使用filter
避免使用行内(inline)样式
避免使用“*”设置{margin：0；padding：0；}
使用伪类清除浮动</code>
</pre>

减少使用影响性能的属性。
<pre>
<code>position:absolute;
float:left;//如这些定位或浮动属性，如需使用，优先使用定位。</code>
</pre>

减少在`CSS`中使用滤镜表达式和图片repeat，尤其在body当中，渲染性能极差，如果需要用repeat的话，图片的宽或高不能少于8px。

JavaScript书写规范

命名规范
<pre>
<code>常量名
全部大写并且单词间用下划线分隔
如：CSS_BTN_CLOSE、TXT_LOADING

对象的属性或方法名
小驼峰式(little camel-case)
如：init、bindEvent、updatePosition
示例：Dialog.prototype = {
init: function(){},
bindEvnet:function(){},
updatePosition:function(){},
...
};
类名(构造器)
-->小驼峰式但首字母大写
-->如：Current、DefaultConfig
函数名
-->小驼峰式
-->如：current()、defaultConfig()
变量名
-->小驼峰式
-->如:current、defaultConfig

私有变量名
    -->小驼峰式但需要用_开头
    -->如：_current、_defaultConfig</code>
</pre>

代码格式。
<pre>
<code>"()"前后需要跟空格
"="前后需要跟空格
","后面需要跟空格
JSON对象需格式化对象参数

if、while、for、do语句的执行体用"{}"包起来</code>
</pre>

"{}"格式如下：

<pre>
<code>if (a==1) {
    //代码
};</code>
</pre>

避免额外的逗号。

<pre>
<code>var arr = [1,2,3,];//最后的逗号不要有</code>
</pre>

`for-in`循环中须用hasOwnProperty方法检查成员是否为自身成员，避免来自原型链上的污染。

长语句可考虑断行。
<pre>
<code>TEMPL_SONGLIST.replace('{TABLE}', da['results'])
.replace('{PREV_NUM}', prev)
.replace('{NEXT_NUM}', next)
.replace('{CURRENT_NUM}', current)
.replace('{TOTAL_NUM}', da.page_total);</code>
</pre>

为了避免和`JSLint`的检验机制冲突，“.”或“+”这类操作符放在行尾。

<pre>
<code>TEMPL_SONGLIST.replace('{TABLE}', da['results']).
    replace('{PREV_NUM}', prev).
    replace('{NEXT_NUM}', next).
    replace('{CURRENT_NUM}', current).
    replace('{TOTAL_NUM}', da.page_total);</code>
</pre>

如果模块代码中，使用其他全局变量想跳过JSLint的检查，可在该文件中添加/*global*/声明。

<pre>
<code>/*global alert: true, console:true, top:true, setTimeout:true*/</code>
</pre>

使用严格的条件判断符。用===代替==，用!==代替!=，避免==产生的陷阱。

*  在条件判断时，这样的一些值表示false。
<pre>
<code>null
undefined与null相等
字符串''
数字0
NaN</code>
</pre>
* 在==时，则会有一些让人难以理解的陷阱。
<pre>
<code>(function(){
    var undefined;
    undefined == null;//true
    1 == true;//true
    2 == true;//false
    0 == false;//true
    0 == '';//true
    NaN == NaN;//false
    [] == false;//true
    [] == ![];//true
})();</code>
</pre>
* 对于不同类型的`==`判断，有这样一些规则，顺序自上而下：
<pre>
<code>undefined与null相等
一个是number一个是string时，会尝试将string转换为number
尝试将boolean转换为number的0或1
尝试将Object转换成number或string</code>
</pre>

而这些取决于另外一个对比量，即值的类型，所以对于0、空字符串的判断，建议使用`===`。<br/>`===`会先判断两边的值类型，类型不匹配时为`false`。

下面类型的对象不建议用new构造：
<pre>
<code>new Number
new String
new Boolean
new Object //用{}代替
new Array //用[]代替</code>
</pre>

引用对象成员用`obj.prop`代替obj["prop"] ，除非属性名是变量。

从number到string的转换。
<pre>
<code>/推荐写法/
var a = 1;
typeof(a); //"number"
console.log(a); //1
var aa = a + '';
typeof(aa); //"string"
console.log(aa); //'1'
/不推荐写法/
new String(a)或a.toString()</code>
</pre>

从string到number的转换，使用parseInt，必须指定第二个参数的进制。
<pre>
<code>/**推荐写法*/
var a = "1";
var aa = parseInt(a,10);
typeof(a); //"string"
console.log(a); //"1"
typeof(aa); //"number"
console.log(aa); //1</code>
</pre>
从float到integer的转换。
<pre>
<code>/**推荐写法*/
Math.floor/Math.round/Math.ceil
/**不推荐写法*/
parseInt</code>
</pre>
字符串拼接应使用数组保存字符串片段，使用时调用join方法。避免使用+或+=的方式拼接较长的字符串，每个字符串都会使用一个小的内存片段，过多的内存片段会影响性能。
<pre>
<code>/**推荐的拼接方式array的push、join*/
var str=[],
    list=['测试A','测试B'];
for (var i=0 , len=list.length; i < len; i++) {
    str.push( '<div>'+ list[i] + '</div>');
};
console.log(str.join('')); //<div>测试A</div><div>测试B</div>
/** 不推荐的拼接方式+=*/
var str = '',
    list=['测试A','测试B'];
for (var i = 0, len = list.length; i< len; i++) {
    str+='<div>' + list[i] + '</div>';
};
console.log(str); //<div>测试A</div><div>测试B</div></code>
</pre>

尽量避免使用存在兼容性及消耗资源的方法或属性。
<pre>
<code>不要使用with，void，evil，eval_r，innerText</code>
</pre>

注意HTML分离，减小reflow，注意性能。优化reflow的方法如下：

1. 不要一条一条地修改 DOM 的样式。与其这样，还不如预先定义好 css 的 class，然后修改 DOM 的 className：
    <pre>
    <code>// 不好的写法
    var left = 10,
    top = 10;
    el.style.left = left + "px";
    el.style.top  = top  + "px";
    // 推荐写法
    el.className += " theclassname";</code>
    </pre>
2. 把 DOM 离线后修改。如：
    + 使用 documentFragment 对象在内存里操作 DOM。
    + 先把 DOM 给 display:none (有一次 repaint)，然后你想怎么改就怎么改。比如修改 100 次，然后再把他显示出来。
    + clone 一个 DOM 节点到内存里，然后想怎么改就怎么改，改完后，和在线的那个的交换一下。
3. 不要把 DOM 节点的属性值放在一个循环里当成循环里的变量。不然这会导致大量地读写这个结点的属性。
4. 尽可能的修改层级比较低的 DOM节点。当然，改变层级比较底的 DOM节点有可能会造成大面积的 reflow，但是也可能影响范围很小。
5. 为动画的 HTML 元件使用 fixed 或 absoult 的 position，那么修改他们的 CSS 是会大大减小 reflow 。
6. 千万不要使用 table 布局。因为可能很小的一个小改动会造成整个 table 的重新布局。

图片规范

命名应用小写英文、数字、_组合，便于团队其他成员理解。
<pre>
<code>header_btn.gif
header_btn2.gif</code>
</pre>

页面元素类图片均放入img文件夹，测试用图片放入img/testing文件夹，psd源图放入img/psdimg文件夹。

图片格式仅限于gif、png、jpg等。

背景图片尽可能用sprite图，减小http请求。

注释规范：

JavaScript、CSS文件注释需要标明作者、文件版本、创建/修改时间、函数描述等信息。
<pre>
<code>/*注释区域/</code>
</pre>
中间可添加如下信息：
<pre>

<code>@file 文件名
@addon 把一个函数标记为另一个函数的扩张，另一个函数的定义不在源文件中
@argument 用大括号中的自变量类型描述一个自变量
@author 函数/类作者的姓名
@base 如果类是继承得来，定义提供的类名称
@class 用来给一个类提供描述，不能用于构造器的文档中
@constructor 描述一个类的构造器
@deprecated 表示函数/类已被忽略
@exception 描述函数/类产生的一个错误
@exec @extends 表示派生出当前类的另一个类
@fileoverview 表示文档块将用于描述当前文件，这个标签应该放在其它任何标签之前
@final 指出函数/类
@ignore 让jsdoc忽视随后的代码
@link 类似于@link标签，用于连接许多其它页面
@member 定义随后的函数为提供的类名称的一个成员
@param 用大括号中的参数类型描述一个参数
@private 表示函数/类为私有，不应包含在生成的文档中
@requires 表示需要另一个函数/类
@return 描述一个函数的返回值
@see 连接到另一个函数/类
@throws 描述函数/类可能产生的错误
@type 指定函数/成员的返回类型
@version 函数/类的版本号</code>
</pre>

Web前端开发规范文档

基本准则

通用规范

文件规范

HTML书写规范

CSS书写规范

JavaScript书写规范

图片规范

注释规范：

相关文章

网友评论

延伸阅读

深度阅读

栏目导航

热点阅读