β

12 Oak Inc 前端开发编码规范

千娱千寻网团队博客 211 阅读

为提高团队协作效率,便于后台人员添加功能及前端后期优化维护, 输出高质量的文档, 特制订此文档。本规范文档一经确认, 前端开发人员必须按本文档规范进行前台页面开发。本文档如有不对或者不合适的地方请及时提出, 经讨论决定后更改。

基本准则

符合web标准, 语义化html, 结构表现行为分离, 兼容性优良。 页面性能方面, 代码要求简洁明了有序, 尽可能的减小服务器负载, 保证最快的页面解析速度。

文件规范

1.  html, css, js, images等文件均统一保存至项目约定的目录中,不得任意放置文件。

2.  html文件命名: 统一使用.html文件后缀。根据页面实现功能采用英文语义命名,如首页(index.html),邀请页(invite.html)。如文件含义无法用一个单词描述,则采用“驼峰法”命名(首字符小写,每个单词的第一个字母大写),如“帮助信息中的关于我们”页面,命名方式为helpAbout.html或者helpAboutUs.html。

3.  css文件命名: 采用英文语义和“驼峰法”命名。全站统一使用一个公用css文件,命名为common.css。在各页面如有必要,可单独使用一个样式,命名为该html页面文件名加上后缀css。比如邀请页需要单独引入一个样式,则命名为invite.css。其它功能模块样式文件可根据功能命名,并在该功能出现的页面引入,比如幻灯片样式,命名为slide.css。一个页面内css文件不要超过两个,一个是公用common.css文件,另一个是该页面的独立样式(该页面独有功能样式一并写入其中)。如果有几个页面布局差不多,比如商品陈列页和商品历史购买页,可公用一个样式,命名方式为shopList.css ( 语义化,驼峰法 ) 。

4.  javascript文件命名: 参照css命名, 共用JS命名为common.js,其它页面根据html页面名称命名。功能模块根据功能名称语义化驼峰法命名,如js倒计时文件,命名为countDown.js 。

HTML编码规范

1 文档声明:统一使用html5文档声明,不再使用xhtml声明。

<!DOCTYPE HTML>

2 文档编码,全部页面统一使用utf-8编码格式。

         <meta charset=”utf-8”/>

3 注释规范。代码原作者根据需要对页面中添加注释。注释格式如下:

         <!–这里是注释(代码功能描述或其它) 注释人 注释时间–>

团队协作时,修改人必须对修改过的地方添加注释。注释格式如下:

         <!–修改原因 注释人 注释时间–>

在注释中,注释原因请使用中文。注释人名使用程序员拼音,如liujin。注释时间统一使用格式 2012/07/24(年月日)。

模块内容较多或者嵌套较多时,必须在标签结束时添加结束注释。

<!– end  #id ( .class) –>

4  html,css,javascript分离。如无特殊必要,尽量不在html文档中直接写css样式和javascript脚本程序。

5 样式和脚本引入时忽略type属性。

不推荐的写法

<link type=”text/css” href="http://team.xunclub.com/”template/css/common.css”/>

<script type=”text/javascript” src="”template/js/common.js”></script>

推荐的写法

<link  href=”template/css/common.css”/>

<script  src="”template/js/common.js”></script>

6  html默认的块状元素在布局时另起一行,并缩进每个子元素。如:

<ul>

    <li>元素一</li>

    <li>元素二</li>

</ul>

<div>

    <p>段落1</p>

    <p>段落2</p>

    <p><span>段落3.1</span><span>段落3.2</span> </p>

</div>

7 所有html元素必须闭合,即便是<br /><img /><meta />这样的标签,也必须使用 /> 闭合。

8 所有元素名和属性名必须使用小写。即便是使用dreamweaver工具,由dw自动生成的js事件,如onMouseOver,也必须改写为onmouseover。所有的属性值必须用成对的双引号包含。如果该属性没有值,则重复本身。

不推荐的写法:

<input type=”text” name=”user”onBlur=”checkInput()”/>

<input type=”checkbox”name=”sex” value=”男”checked />

推荐的写法:

<input type=”text” name=”user”onblur=”checkInput()”/>

<input type=”checkbox”name=”sex” value=”男”checked=”checked” />

9 表单规范。

         9.1 form的name属性命名统一使用“表单功能”+“Form”驼峰式,比如登陆表单,规范如下:

<form name=” loginForm” >

如果表单中有图片图片控件,必须在form中添加enctype=“multipart/form-data” 属性,设置表单的MIME编码。

<form name=”xxxForm” enctype=”multipart/form-data”>

         9.2 表单内控件命名方式参照9.1。

         9.3 描述性的信息使用label标签。

<p><label>用户名</laber><input  type=”text” name=”userName” /></p>

10 代码中不能单独出现标签开始符(<),和结束符 (>),以及逻辑与(&),必须分别被编码成&lt; &gt; &amp;

11 代码必须缩进,使文档看起来流畅整洁。统一使用一个TAB键缩进。压缩文件除外。

12  html标签的id属性和class属性命名必须保持语义化,杜绝使用数字和汉语拼音命名(可读性差)。多个单词用“-“链接,字符全部小写。如果自定义标签属性,请以”data-“开头。

如留言:<div class=”message”>…</div>

如商品列表:<div id=”products-list”>…</div>

用户头像上添加用户的身份ID: <img src="”user/images/sina_1001.jpg”data-uid=”1001”/>

13 必须为多媒体标签添加alt属性,如图片,视频。必须为超链接添加title属性。

         <img src="”images/caite.jpg”alt=”段林希代言彩特手表”/>

如果页面关键词是段林希和彩特手表,那么这张图片上将出现两个关键词各一次,利于SEO优化。

14  h1-h6号,ul标签的使用。

14.1 标题根据重要性用h1~h6号。一个页面内只能有一个h1标签,一般用于网站头部的公司(网站)名称上。页面内相对比较重要的并行模块标题(如各个活动,限时抢购活动,预定活动等)使用h2号标签。侧边栏信息标题(活动时间,活动动态)使用h3标签。

14.2 列表模块,比如评论列表,动态列表,均采用ul标签布局。

         14.3 内联元素中不可使用块状元素。

错误写法

<a href=”xxx”title=”xxx”><h2>超链接</h2></a>

正确写法

<h2><a href=”xxx”title=”xxx”>超链接</a></h2>

15 在所有的url属性值的最后加上”/”,避免两次http请求。

<a  href=”http://i.xunclub.com/“  target=”_blank” title=”影响力“>影响力</a>

16 尽量减少div的嵌套。重要!

17 检测html文档的正确性。

错误检查: 火狐浏览器查看页面源文件,火狐浏览器会描红错误部分。

页面验证: 将html文档提交到w3c官方验证。地址:http://validator.w3.org/

18 本部分持续添加修改中。

CSS编码规范

1  id和class命名必须语义化,命名尽量简洁,可读性高.

作者信息 <div class=”author”>…</div>

日期信息 <div class=”date”>…</div>

多层嵌套时,以功能命名,并用“-”连接。注意是连接符,不是下划线。(善用前缀,防止样式冲突。)

二级菜单

<ul class=”menu”>

    <li>

          <a href="http://team.xunclub.com/””>父菜单1</a>

          <ul class=”sub-menu”>

               <li>子菜单1.1</li>

               <li>子菜单1.2</li>

         </ul>

    </li>

    <li>

         <a href=””>父菜单2</a>

         <ul class=”sub-menu”>

                <li>子菜单2.1</li>

                <li>子菜单2.2</li>

         </ul>

    </li>

</ul>

留言列表模块

                   <div id=”message”>

                            <ul class=”message-ul”>

                                     <li class=”message-ul-li”>留言一</li>

                                     <li class=”message-ul-li”>留言二</li>

                                     <li class=”message-ul-li”>留言三</li>

                            </ul>

                   </div>

模块或功能区最外层标签统一使用ID命名,内层全部使用class命名。(为JS预留的ID选择器除外,ID选择器请以“js-”开头)

评论模块

<div id=”comment”>

         <div class=”comment-header”>

                   <span class=”comment-date”>2012年07月25日</span>

                   …

                  <span class=”comment-show-all”id=”js-comment-show-all”>查看全部留言</span>

         </div>

         <div class=”comment-content”>

                   …

         </div>

</div

在css样式中应避免多余的祖先元素。

推荐的写法

.comment{

         padding:10px;

         color:#000;

}

不推荐的写法

div.comment{    /*div是多余的*/

         padding:10px;

         color:#000;

}

2 简化css的写法

不推荐的写法

.example{

         font-family:”microsoft yehei”,”黑体”,arial,sans-serif;

         font-size:24px;

         line-height:32px;

         padding-left:15px;

         padding-bottom:10px;

}

推荐的写法

.example{

                   font : 24px/32px  ”microsoft yehei”,”黑体”,arial,sans-serif;

                   padding: 0 0 10px 15px;  

}

3  css样式表必须整洁,查找方便。推荐排版方式如下:

/*在模块或者功能区样式开始前注释功能说明。这里的注释代表上面一个功能样式的结束和下一个功能样式的开始。*/

/*注释格式: 功能描述 注释人 时间(年-月-日)*/

/*该处样式经第二人修改时,应在原样式的下面或者修改属性的后面修改,并且添加修改说明和修改人信息*/

.example{  /*选择器顶格起排*/

         font-family:”microsoft yehei”,”黑体”,arial,sans-serif;   /*属性名距离顶格一个TAB键*/

         font-size:24px;     /*多个属性换行*/

         line-height:32px;  /*如有必要对某个属性进行注释,则注释在该属性结束符‘;‘ 分号后面*/

         padding-left:15px;

         padding-bottom:10px;

         color:#fff;  /*颜色统一采用16进制,三个色相的两个数字或者字母相同,则可简写*/

}/*这里写完后空一行再写其它的id或class*/

4 兼容性问题。

1.开发时,先在智能浏览器下开发调试(如firefox,chrome,IE9),使基础代码符合w3c规范。建议根据项目需要部分或者全部采用css3.0新标准,智能浏览器调试无误后,再针对IE浏览器做兼容性测试,使代码能够兼容IE6,7,8。

2.根据开发者个人习惯,自行决定模块开发完成,页面开发完成,项目开发完成后做各浏览器兼容性处理。这里推荐在一个页面完成开发后,做各浏览器兼容处理。原因1,一个模块开发完成做处理,重复度高,浪费时间。2,一个项目结束后做处理,工作量大,时间不够。

3.兼容代码。针对IE浏览器做hacks, 补丁程序需要单独成页,html页面根据IE版本做选择性样式载入。Css补丁程序文件命名规则:ie.css,  ie6.css,  ie7.css,  ie8.css 或者ie67.css  ie78.css

4.Html判断载入css样式:

IE7 专用(IE6,8,9同理)

<!–[if IE 7]>

         <link rel=”stylesheet” href=”ie7.css”/>

<![endif]–>

IE8 以下(含IE8)(小于为lt ,大于为gt, 大于等于为gte,  小于等于为 lte )(其它同理)

<!–[if lt IE 9]>

         <link rel=”stylesheet” href=”ie78.css”/>

<![endif]–>

5 重置浏览器部分默认样式。请将以下代码添加至全局样式文件common.css 头部。可根据项目实际情况修改。

html,body, div, dl, dt, dd, ul, ol, li,h1, h2, h3, h4, h5, h6, pre, code,form, fieldset, legend, input, button,textarea, p, blockquote, th, td{

    margin: 0;

    padding: 0;

}

fieldset, img{

    border: 0;

}

:focus{

    outline: 0;

}

address, caption, cite, code, dfn,em, strong, th, var, optgroup{

    font-style: normal;

    font-weight: normal;

}

h1, h2, h3, h4, h5, h6{

    font-size: 100%;

    font-weight: normal;

}

abbr, acronym{

    border: 0;

    font-variant: normal;

}

input, button, textarea,select, optgroup, option{

    font-family: inherit;

    font-size: inherit;

    font-style: inherit;

    font-weight: inherit;

}

code, kbd, samp, tt{

    font-size: 100%;

}

input, button, textarea, select{

    *font-size: 100%;  /*ie下*/

}

body{

    line-height: 1.5; /*1.5倍行距24px*/

}

ol, ul{

    list-style: none;

}

table{

    border-collapse: collapse;

    border-spacing: 0;

}

caption, th{

    text-align: left;

}

sup, sub{

    font-size: 100%;

    vertical-align: baseline;

}

:link, :visited , ins{

    text-decoration: none;

}

blockquote, q{

    quotes: none;

}

blockquote:before, blockquote:after,q:before, q:after{

    content: ”;

    content: none;

}

6 设置全局默认css样式。

6.1 规定统一使用<div class=”clear”></div>代码清除浮动。

.clear{

         clear:both;

         float:none;

}

6.2 根据项目实际情况设置全局样式。

body{

       color:#000;

       background:#fff;

       font:14px “microsoft yahei”,”黑体”,arial,sans-serif;

}

a, a:visited{

         color:#00f;

}

a:hover{

         Color:#f00;

}

         …

将全局样式加入到重置样式后面。

7  CSS完成后及时验证。W3c验证地址. http://jigsaw.w3.org/css-validator/

8 本部分持续添加修改中。

JavaScript规范

1  js必须作为文件来存储,不要将j s代码写入html文档,除非这段js代码有特殊作用,非引入html中不可。在页面底部引入js文件,除了特殊js文件,如jq库和html载入时就需要用到的js文件。

2 注释。函数(功能)开始前必须注释,规范如下:

单行注释: // 功能描述 注释人 时间

多行注释:

/*

*这里是注释

*这里是注释

*/

如果函数复杂,请开发者务必注明相关参数说明。格式如下:

/*

* 倒计时函数  By LiuJin  2012-05-29

* @param str: 活动到期时间,剩余多少时间

* @param i: 本倒计时要显示的页面位置class=”T-i”

* @param pid: 计时的活动专场ID

*/

function showTime(str,i,pid){

         …

}

3 命名。函数均采用“驼峰法”命名。变量全部采用小写命名,多个字符之间用下划线连接。保持名称的语义化。

4 语句。尽量在 一行只写一条语句。语句以分号结尾,不建议省略。

5 缩进。函数功能模块开始,顶格书写。函数内代码根据上级缩进。一次缩进使用一个TAB键。

6 一个项目中,如无必要,不能引入两个js库,这里建议采用jquery库1.6版本。原生JS实现不太复杂的功能,尽量使用原生JS开发。

7 前后端数据传输约定。采用ajax方式传输数据,数据格式为json。

8 前端Js开发人员在完成开发后需要经常检查代码,不断力求精简高效,请求反应速度快。

本部分持续添加修改中。

作者:千娱千寻网团队博客
国内新锐购物社交平台千娱千寻网团队博客
原文地址:12 Oak Inc 前端开发编码规范, 感谢原作者分享。

发表评论