前端编码规范

JerryXia 发表于 June 20, 2013 , 阅读 (4,315)

为了保证前端代码质量，提高团队协作开发效率，提升沪江网站产品质量，制定此文档。文档包含通用规范、HTML规范、CSS规范和Javascript规范。文档也在不断修订完善中。

一、通用规范**

文件与目录

一律小写，必须是英文单词或产品名称的拼音，多个单词用连字符(-)或下划线(-)连接。只能出现英文字母、数字、连字符和下划线，严禁出现中文。
该命名规范适用于 html, css, js, swf, php, xml, png, gif, jpg, ico 等前端维护的所有文件类型和相关目录。
js 和 css 压缩文件, 统一以 min 结尾, 比如源码文件为 xxx.js, 压缩后为 xxx.min.js。
css 统一存放在style或css文件夹下。
js 统一存放在js文件夹下。
图片统一存放子images或imgs等相关目录下。
文件编码格式建议使用utf-8。
建议使用4个空格来表示缩进，不要使用tab键。

字体

一般情况下推荐使用字体为：Verdana, Helvetica, SimSun, Arial, "Arial Unicode MS", MingLiu, PMingLiu, "MS Gothic", sans-serief。
中文字体属性中尽量避免出现汉字，如：“宋体”、“微软雅黑”等。而应该用SimSun、Microsoft Yahei。常用汉字字体的英文名列表如下：
- 宋体——SimSun
- 黑体——SimHei
- 隶书——LiSu
- 楷体——KaiTi_GB2312
- 幼圆——YouYuan
- 微软雅黑——Microsoft Yahei
日文推荐字体列表：Osaka, “ＭＳＰゴシック”, Arial, “sans-serif”。
中日英混合推荐字体列表：Verdana, Lucida Sans Regular, Lucida Sans Unicode, Arial, sans-serif。
等宽字体推荐列表：Lucida Console, Monaco, Courier New, mono, monospace。

图片

图片格式仅限于png、jpg和gif。
能不使用半透明的图片就尽量不要使用。
css背景图片优先采用png8格式。
css背景图片尽可能使用sprite技术合并图片，减少http请求。sprite可使用texturepacker等工具制作。
在保证视觉效果的前提下尽量降低图片尺寸和质量。一般的单张图片控制在100k以内

项目管理与发布

使用svn或git进行版本管理。在提交代码前必须先更新。
任何修改都需通过浏览器测试后再提交。测试浏览器包括：chrome、firefox、IE(6-10)、360、safari。
维护项目上线前需注意js、css、sprite image等静态文件的缓存问题，必要时采用版本号来强制更新。
js和css可使用静态合并服务器。http://res.hjfile.cn 上安装了nginx_concat_module模块。这样前端就可以直接采用url组合方式合并多个js/css文件，如：
<script src=”http://res.hjfile.cn/js/lib/jq/1.8.3/??jquery.min.js,plugins/jbox-2.3.min.js”></script>
<link rel=”stylesheet” href=”http://res.hjfile.cn/css/test/??global.css,home.css?t=20130412.css”>

注意：使用2个??来触发文件合并，文件之间使用逗号分隔。最后也可以增加一个t参数标记防止更新后的缓存问题。

二、HTML规范

基本编码规范

文档类型统一使用：<!DOCTYPE html>。
编码推荐使用utf-8：<meta charset="utf-8" />
填写完整的头部和元信息，如title、keywords、description等。
css 尽量放在头部<head>引用。
不要在html中写内联css样式。
js 尽量放在<body>底部。
使用符合语义的HTML标签元素。
元素的标签和属性名一律小写，属性值必须加双引号。
通过给元素设置自定义属性来存放与 js 交互的数据，属性名格式为 data-xx (例如：data-myname)。
正确区分自闭合元素和非自闭合元素. 非法闭合包括：<br>..</br>、<script />、<iframe />, 非法闭合会导致页面嵌套错误问题。
所有的HTML标记都必须合理嵌套。如：内联元素不可以嵌套块状元素。
避免不必要的标签嵌套。
为含有描述性表单元素(input，textarea)添加label。
给图片加上alt属性，链接加上title属性。
h1到h5的使用，应遵循从大到小的原则，体现文档的结构，并有利于搜索引擎的查询。
文档中不要出现无意义的空格和换行。

id和class命名约定

id 和 class 的命名总规则为：内容优先，表现为辅。首先根据内容来命名，比如 main-nav。如果根据内容找不到合适的命名，可以再结合表现来定，比如 skin-blue、present-tab、col-main。
id 和 class 名称一律小写，多个单词用连字符连接，比如 main-content。
id 和 class 名称中只能出现小写的26个英文字母、数字、连字符(-)或下划线(_)，任何其它字符都严禁出现。
id 和 class尽量用英文单词命名。确实找不到合适的单词时，才考虑使用产品的中文拼音。
在不影响语义的情况下, id 和 class 名称中可以适当采用英文单词缩写，比如 col、nav、bot等，但切忌自造缩写。
id 和 class 名称中的第一个词必须是单词全拼或语义非常清晰的单词缩写，比如 sidebar，col。

常用命名

布局

整体布局：layout、wrapper
上下左中右：top、bottom、left、center、right
容器：container、box
页头：header
页面主体：main
页脚：footer
侧边栏：sidebar
竖栏目：col
导航：nav
菜单：menu
内容条：bar

模块

标题：title
内容：content
列表：list
按钮：btn
输入框：input
标签：label
切换标签：tab
图标：icon
背景：bg
对话框：dialog
提示：tip
消息：msg
注释：note
描述：disc

功能

登陆注册：login、register
搜索：search
广告：banner
指南：guide
下载：download
产品：product
新闻：news
站标：logo
链接：link
合作伙伴：partner
版权：copyright

三、CSS规范

为了网站有统一的风格和一致的用户体验，一个网站必须要有一个公共的基础css样式，如base.css、common.css、global.css等。基础样式不能随意修改，防止影响其他业务。
除开公共的css，每个项目都有自己的业务相关的css。
尽量提高样式重复使用率，但要控制粒度，不要过细。
背景图片遵循通用规范中的图片规范。
样式中中文字体使用英文名称，如：SimSun。
使用table标签时(尽量避免使用table标签), 请不要用width/ height/cellspacing/cellpadding等table属性直接定义表现, 应尽可能的利用table自身私有属性分离结构与表现, 如thead,tr,th,td,tbody,tfoot,colgroup,scope等。
合理使用缩写，如 color、margin、padding、background、font 等。
注意css优先级：行内样式(inline style) > id选择符 > 样式(class)、伪类(pseudo-class)、属性(attribute)选择符 > 类别(type)，伪对象(pseudo-element)。
不要重复定义可继承的样式，但是要注意浏览器可能用一些默认值覆盖你的定义。
10.id前面不要添加元素限定。如 div#main-content。
类名命名建议统一前缀。如使用 .widget, .widget-title, .widget-content，而不是 .widget .title, .widget .content。
尽量不要在复合选择器中使用无语义的类型选择器。如：.list div, .content span 等。
尽量不要使用超过3个以上的组合选择器。如：.list ul li a 等。
不要使用@import 引入css，这会影响加载性能。
尽量不要使用 !important。
链接伪类一定要按照a:link、a:visited、a:hover、a: active的顺序书写。
避免使用expression表达式。
添加必要的注释。

四、Javascript规范

基本开发规范

统一使用驼峰式命名。变量和函数首字母小写，类名首字母大写
声明变量时必须加上 var 关键字。
尽量减少全局变量的使用。
js代码范式：
(function(){
```
   //代码
```
})();
$(function(){
```
   //代码
```
});
语句总是以分号结尾。
标准特性优于非标准特性(如果类库有提供, 优先使用类库中的函数)。
避免使用 eval ，只在解析序列化串等少数情况下时使用 eval 。
不要使用字符串作为 setTimeout、setInterval 的第一个参数。如不要使用：setTimeout(‘foo(1,2)’, 1000)。
不推荐使用setInterval。因为当回调函数的执行被阻塞时，setInterval 仍然会发布更多的回调指令。
js是弱类型语言，很多情况下会自动应用强制类型转换。如：10 == ’10′, 10 == ‘+10′, 10 == ’010′。因此，使用前注意数据类型转换。如： ” + 10 === ’10′, Number(’010′) === 10, parseInt(’010′, 10) === 10。
禁止使用 with 语句。
使用 Array/Object 直接量, 避免使用 Array/Object 构造器。
禁止修改内置对象的原型，除非兼容新的js，如Array.forEach。
避免使用document.write。
添加必要的注释。
超过20k的js发布时必须经过压缩。推荐使用google closure compiler进行优化压缩。

类库使用规范

为了方便开发和维护，统一使用 jquery 作为公共基础类库，版本推荐使用：1.8.3。统一使用： http://res.hjfile.cn/js/lib/jq/1.8.3/jquery.min.js。原来使用其他版本jquery的可不改变，以免造成兼容性问题。
原则上不允许使用其他基础类库，如prototype、YUI3等。
其他功能可使用基于jquery的插件或自主开发。
触屏站暂时推荐使用zeptojs：http://res.hjfile.cn/js/lib/zepto/1.0/zepto.min.js。
jquery插件需统一管理，统一存放在：http://res.hjfile.cn/js/lib/jquery/1.8.3/plugins/ 里面。

公共类库一览表（http://res.hjfile.cn）

jquery

jquery基础库：js/lib/jq/1.8.3/jquery.min.js
弹窗插件：js/lib/jq/1.8.3/plugins/jbox-2.3.min.js
cookie插件：js/lib/jq/1.8.3/plugins/cookie-1.3.1.min.js
图片轮播插件：js/lib/jq/1.8.3/plugins/jcarousel-0.3.0.min.js
表单校验插件：js/lib/jq/1.8.3/plugins/validation-1.12.min.js
页面跳转hashchange插件：js/lib/jq/1.8.3/plugins/hashchange-1.3.min.js

zeptojs

zeptojs基础库：js/lib/zepto/1.0/zepto.min.js

附录一：前端页面优化手段

常规优化

CSS置顶，JS置底。
静态资源外联、合并、压缩。
图片优化。（Png使用pngcrush；Gif使用gifsicle；Jpeg使用jpegtran）
图片延迟加载。（主要针对首屏外的图片。）
使用CSS Sprite，首屏图片全部合到一张图上。
静态文件上CDN。（静态文件的下载能提速20%左右。）
静态文件设置强缓存。
HTML压缩。（Gzip后减少50%。）

增强优化

基础库定制。
页面数据存储优化。（采用script/template、隐藏textarea等方式）
首屏CSS检测。（对首屏用到的CSS进行检测，将不属于首屏的CSS代码单独打包并移到首屏之外进行延迟加载）
js按需加载。

附录二：资源参考网站

HTML

HTML Spec 4.0.1 http://www.w3.org/TR/REC-html40/
HTML Spec 5.1 http://www.w3.org/html/wg/drafts/html/master/
HTML5 Rocks http://www.html5rocks.com/zh/

Javascript

Mozilla Javascript开发文档 https://developer.mozilla.org/zh-CN/docs/JavaScript
Microsoft Javascript参考 http://msdn.microsoft.com/zh-cn/library/ie/yek4tbz0(v=vs.94).aspx
文档对象模型 DOM http://msdn.microsoft.com/zh-cn/library/hh772384(v=vs.85).aspx
Javascript 秘密花园 http://bonsaiden.github.io/JavaScript-Garden/zh/

CSS

CSS中文参考 http://css.doyoe.com
CSS3 files http://www.css3files.com/

综合

caniuse 浏览器特性速查 http://caniuse.com
html5移动网站开发模板 https://github.com/h5bp/mobile-boilerplate

[ Web标准 ] [ Web开发 ]