前端编码规范

JerryXia 发表于 , 阅读 (2,085)

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

一、通用规范**

文件与目录

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

字体

  1. 一般情况下推荐使用字体为:Verdana, Helvetica, SimSun, Arial, "Arial Unicode MS", MingLiu, PMingLiu, "MS Gothic", sans-serief。
  2. 中文字体属性中尽量避免出现汉字,如:“宋体”、“微软雅黑”等。而应该用SimSun、Microsoft Yahei。常用汉字字体的英文名列表如下:

    • 宋体——SimSun
    • 黑体——SimHei
    • 隶书——LiSu
    • 楷体——KaiTi_GB2312
    • 幼圆——YouYuan
    • 微软雅黑——Microsoft Yahei
  3. 日文推荐字体列表:Osaka, “MSPゴシック”, Arial, “sans-serif”。
  4. 中日英混合推荐字体列表:Verdana, Lucida Sans Regular, Lucida Sans Unicode, Arial, sans-serif。
  5. 等宽字体推荐列表:Lucida Console, Monaco, Courier New, mono, monospace。

图片

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

项目管理与发布

  1. 使用svn或git进行版本管理。在提交代码前必须先更新。
  2. 任何修改都需通过浏览器测试后再提交。测试浏览器包括:chrome、firefox、IE(6-10)、360、safari。
  3. 维护项目上线前需注意js、css、sprite image等静态文件的缓存问题,必要时采用版本号来强制更新。
  4. 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规范

基本编码规范

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

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规范

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

四、Javascript规范

基本开发规范

  1. 统一使用驼峰式命名。变量和函数首字母小写,类名首字母大写
  2. 声明变量时必须加上 var 关键字。
  3. 尽量减少全局变量的使用。
  4. js代码范式:

    (function(){

       //代码

    })();
    $(function(){

       //代码

    });

  5. 语句总是以分号结尾。
  6. 标准特性优于非标准特性(如果类库有提供, 优先使用类库中的函数)。
  7. 避免使用 eval ,只在解析序列化串等少数情况下时使用 eval 。
  8. 不要使用字符串作为 setTimeout、setInterval 的第一个参数。如不要使用:setTimeout(‘foo(1,2)’, 1000)。
  9. 不推荐使用setInterval。因为当回调函数的执行被阻塞时,setInterval 仍然会发布更多的回调指令。
  10. js是弱类型语言,很多情况下会自动应用强制类型转换。如:10 == ’10′, 10 == ‘+10′, 10 == ’010′。因此,使用前注意数据类型转换。如: ” + 10 === ’10′, Number(’010′) === 10, parseInt(’010′, 10) === 10。
  11. 禁止使用 with 语句。
  12. 使用 Array/Object 直接量, 避免使用 Array/Object 构造器。
  13. 禁止修改内置对象的原型,除非兼容新的js,如Array.forEach。
  14. 避免使用document.write。
  15. 添加必要的注释。
  16. 超过20k的js发布时必须经过压缩。推荐使用google closure compiler进行优化压缩。

类库使用规范

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

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

jquery

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

zeptojs

  1. zeptojs基础库:js/lib/zepto/1.0/zepto.min.js

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

常规优化

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

增强优化

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

附录二:资源参考网站

HTML

Javascript

CSS

综合

添加新评论