By zhpooer

更新日期:

文章目录
  1. 1. 文件规范
  2. 2. 编辑器配置
  3. 3. HTML规范
    1. 3.1. 模板
    2. 3.2. 建议
      1. 3.2.1. 属性顺序
      2. 3.2.2. 实用为王
      3. 3.2.3. 减少标签的数量
      4. 3.2.4. JavaScript 生成的标签
      5. 3.2.5. 嵌套层级
  4. 4. CSS规范
    1. 4.1. 命名规范
    2. 4.2. 模板
    3. 4.3. 重构步骤约定
    4. 4.4. 建议
      1. 4.4.1. 声明顺序
      2. 4.4.2. 单行规则声明
    5. 4.5. CSS Reset
  5. 5. JS规范
    1. 5.1. jQuery Plugin

不管有多少人共同参与同一项目，一定要确保每一行代码都像是同一个人编写的。

参考1 参考2 参考3

文件规范

  1. css 文件命名：英文命名, 后缀.css. 共用 base.css, 首页index.css, 其他页面依实际模块需求命名。
  2. js 文件命名：英文命名, 后缀.js. 共用 common.css, 其他依实际模块需求命名.

编辑器配置

将你的编辑器按照下面的配置进行设置，以避免常见的代码不一致和差异：

  • 用两个空格代替制表符（soft-tab 即用空格代表 tab 符）。
  • 保存文件时，删除尾部的空白符。
  • 设置文件编码为 UTF-8

HTML规范

  • 文档类型声明及编码: 统一为html5声明类型; 编码统一为utf-8, 书写时利用IDE实现层次分明的缩进;
  • 非特殊情况下样式文件必须外链至<head></head>之间;非特殊情况下javascript文件必须外链至页面底部;
  • 引入JS库文件, 文件名须包含库名称及版本号及是否为压缩版, 比如jquery-1.7.1.min.js; 引入插件, 文件名格式为库名称+插件名称, 比如 jQuery.cookie.js;
  • 所有编码均遵循xhtml标准, 标签 & 属性 & 属性命名 必须由小写字母及下划线数字组成, 且所有标签必须闭合; 属性值必须用双引号包括;
  • 充分利用无兼容性问题的html自身标签, 比如 span, em, strong, optgroup, label 等等; 需要为html元素添加自定义属性的时候, 首先要考虑下有没有默认的已有的合适标签去设置, 如果没有, 可以使用须以”data-”为前缀来添加自定义属性，避免使用”data:”等其他命名方式;
  • 语义化html, 如 标题根据重要性用h(同一页面只能有一个h1), 段落标记用p, 列表用ul, 内联元素中不可嵌套块级元素;
  • 书写链接地址时, 必须避免重定向，例如：href=”http://www.example.com/”, 即须在URL地址后面加上/；
  • 在页面中尽量避免使用style属性,即style=”…”，应该尽量使用class或者id来定义新的样式， 然后再对应的CSS文件里面修改;

模板

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

<!DOCTYPE html>
<html>
  <head>
    <!-- 通过明确声明字符编码，能够确保浏览器快速并容易的判断页面内容的渲染方式。 -->
    <meta charset="utf-8">
    <title>Page title</title>
    <meta name="keywords" content="xxxx, xxx, xxxxx" />
    <meta name="description" content="xxxxxxxxxxxxxxxxxxxx" />
    <!-- 通知ie采用最新模式 -->
    <meta content="IE=edge,chrome=1" http-equiv="X-UA-Compatible">
    <!-- 如果是响应式页面，请加上这句 -->
    <meta content="width=device-width, initial-scale=1" name="viewport">
    <!-- 让 360 等双核浏览器采用 webkit 进行页面渲染  -->
    <meta content="webkit" name="renderer" >
    <!-- 缓存头可酌情添加 -->
    <meta http-equiv="Cache-Control" content="max-age=7200" />
    <!-- icon -->
    <link rel="shortcut icon" href="favicon.ico">
    <!-- 根据html5规范，对于引入css和js可以不用指定type属性 -->
    <!-- External CSS -->
    <link rel="stylesheet" href="code-guide.css">
    <!-- In-document CSS -->
    <style>
    </style>
  </head>
  <script type="text/javascript">
    <!-- Google 统计代码 的位置在离</head>最近的位置 -->
  </script>
  <body>
    <img src="images/company-logo.png" alt="Company">
    <h1 class="hello-world">Hello, world!</h1>
    <!-- 注释约定 -->
    <!--
    @name: Drop Down Menu
    @description: Style of top bar drop down menu.
    @author: Andy Huang(andyahung@geekpark.net)
    -->
    <div id="header">
      <div class="xxx">
        <span>HTML行内注释格式</span>
      </div>
    </div><!-- #header end-->
    <!-- JavaScript 要加到html的最后，这样可以提高页面的加载速度 -->
    <script src="code-guide.js"></script>
  </body>
</html>

建议

属性顺序

HTML 属性应当按照以下给出的顺序依次排列，确保代码的易读性。

  • class
  • id, name
  • data-*
  • src, for, type, href
  • title, alt
  • aria-*, role
1
2
3
4
5

<a class="..." id="..." data-modal="toggle" href="#">
  Example link
</a>
<input class="form-control" type="text">
<img src="..." alt="...">

class 用于标识高度可复用组件，因此应该排在首位。id 用于标识具体组件，应当谨慎使用（例如，页面内的书签），因此排在第二位。

实用为王

尽量遵循 HTML 标准和语义，但是不要以牺牲实用性为代价。任何时候都要尽量使用最少的标签并保持最小的复杂度。

减少标签的数量

编写 HTML 代码时，尽量避免多余的父元素。很多时候，这需要迭代和重构来实现。请看下面的案例：

1
2
3
4
5
6
7

<!-- Not so great -->
<span class="avatar">
  <img src="...">
</span>
  
<!-- Better -->
<img class="avatar" src="...">

JavaScript 生成的标签

通过 JavaScript 生成的标签让内容变得不易查找、编辑，并且降低性能。能避免时尽量避免。

嵌套层级

1
2
3
4
5
6
7
8
9
10
11
12
13
14

/* 推荐嵌套层级 */
  <ul class="ui-nav">
    <li class="ui-nav-item"> some text
      <ul class="ui-nav-item-child">
        <li> some text
          <ul class="ui-list">
            <li class="ui-list-item"> some text</li>
          </ul
        ...
       </ul>
    </li>
    <li
    ...
  </ul>

CSS规范

  • 编码统一为utf-8
  • 公用文件：协作开发过程中，会引入默认的base.css(里面包括了css reset、常用的css间距，css字体，css大小等)
  • class与id命名: 样式名称由 小写英文 、 数字 和 _ 来组合命名, 如i_comment, fontred, width200; 避免使用中文拼音, 尽量使用简易的单词组合；命名要语义化, 简明化
  • 为JavaScript预留钩子的命名, 尽量使用id属性，可以更快的获取到dom
  • 书写代码前, 考虑并提高样式重复使用率
  • 背景图片请尽可能使用sprite技术, 减小http请求, 考虑到多人协作开发, sprite按模块制作
  • 必须为大区块样式添加注释, 小区块适量注释
  • 代码缩进与格式: 建议单行书写, 可根据自身习惯, 后期优化会统一处理

命名规范

  • ID: 匈牙利命名法 & 小駝峰式命名法, 如：firstName topBoxList footerCopyright
  • Class: [减号连接符]　如：top-item main-box box-list-item-1，　 尽量使用语义明确的单词命名，避免 left bottom等方位性的词语
  • 避免过度任意的简写。.btn 代表 button，但是 .s 不能表达任何意思。
  • class 名称应当尽可能短，并且意义明确。
  • 使用有意义的名称。使用有组织的或目的明确的名称，不要使用表现形式（presentational）的名称。(语义化)
  • 基于最近的父 class 或基本（base） class 作为新 class 的前缀。

模板

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

/*
@name: Drop Down Menu
@description: Style of top bar drop down menu.
@require: reset.css
@author: Andy Huang(andyahung@geekpark.net)
*/
/* CSS名称+冒号+属性 */
.box1 {float:left;}
/*建议保留{左侧空格，字体名用\包含*/
.box1,.box2,.box3 {font-family:Courier,'Courier New';}
/*避免中文，或使用转义，推荐前者如：*/
.box4 {
  font-family: "Microsoft YaHei";
  font-family:\5fae\8f6f\96c5\9ed1;
}

/* 推荐嵌套层级 */
.ui-icon-rarr{}
.ui-icon-larr{}
.ui-title{}
.ui-nav .ui-list{}
.ui-table .ui-list{}

/* 不推荐 */
.ui-icon-rarr{}
.ui-icon-larr{}
.ui-title{}
.ui-list{}
.ui-nav{}

/* 媒体查询放在尽可能相关规则的附近。不要将他们打包放在一个单一样式文件中或者放在文档底部。*/
.element { ... }
.element-avatar { ... }
.element-selected { ... }

@media (min-width: 480px) {
  .element { ...}
  .element-avatar { ... }
  .element-selected { ... }
}

重构步骤约定

index.html 全部样式附着于 class="xxx" 注： 此时文件中不包含任何一个 id="xxx"
为上一步书写 CSS style
[至此重构完成]
开始书写js交互文件，使用 ID 和 Class 定位被操作句柄
向 index.html 中需要的地方添加 id="xxx" 及 data-xxx="xxx"
[至此交互效果完成]

建议

声明顺序

不做硬性规定

相关的属性声明应当归为一组，并按照下面的顺序排列：

  1. Positioning
  2. Box model
  3. Typographic
  4. Visual

由于定位（positioning）可以从正常的文档流中移除元素，并且还能覆盖盒模型（box model）相关的样式，因此排在首位。 盒模型排在第二位，因为它决定了组件的尺寸和位置。

其他属性只是影响组件的内部（inside）或者是不影响前两组属性，因此排在后面。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

.declaration-order {
  /* Positioning */
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
  z-index: 100;

  /* Box-model */
  display: block;
  float: right;
  width: 100px;
  height: 100px;

  /* Typography */
  font: normal 13px "Helvetica Neue", sans-serif;
  line-height: 1.5;
  color: #333;
  text-align: center;

  /* Visual */
  background-color: #f5f5f5;
  border: 1px solid #e5e5e5;
  border-radius: 3px;

  /* Misc */
  opacity: 1;
}

单行规则声明

对于只包含一条声明的样式，为了易读性和便于快速编辑，建议将语句放在同一行。对于带有多条声明的样式，还是应当将声明分为多行。

这样做的关键因素是为了错误检测 -- 例如，CSS 校验器指出在 183 行有语法错误。如果是单行单条声明，你就不会忽略这个错误；如果是单行多条声明的话，你就要仔细分析避免漏掉错误了。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17


/* Single declarations on one line */
.span1 { width: 60px; }
.span2 { width: 140px; }
.span3 { width: 220px; }

/* Multiple declarations, one per line */
.sprite {
  display: inline-block;
  width: 16px;
  height: 15px;
  background-image: url(../img/sprite.png);
}
.icon           { background-position: 0 0; }
.icon-home      { background-position: 0 -20px; }
.icon-account   { background-position: 0 -40px; }

CSS Reset

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

@charset "UTF-8";
html, body, div, span, applet, object, iframe,
h1, h2, h3, h4, h5, h6, p, blockquote, pre,
a, abbr, acronym, address, big, cite, code,
del, dfn, em, img, ins, kbd, q, s, samp,
small, strike, strong, sub, sup, tt, var,
b, u, i, center,
dl, dt, dd, ol, ul, li,
fieldset, form, label, legend,
table, caption, tbody, tfoot, thead, tr, th, td,
article, aside, canvas, details, embed,
figure, figcaption, footer, header, hgroup,
menu, nav, output, ruby, section, summary,
time, mark, audio, video {
  margin: 0;
  padding: 0;
  border: 0;
  font: inherit;
  font-size: 100%;
  vertical-align: baseline;
}
html { line-height: 1;}
ol, ul { list-style: none; }
table {border-collapse: collapse; border-spacing: 0;}
caption, th, td {text-align: left; font-weight: normal; vertical-align: middle;}
q, blockquote { quotes: none; }
q:before, q:after, blockquote:before, blockquote:after {content: ""; content: none;}
a img { border: none;}
article, aside, details, figcaption, figure, footer, header, hgroup, main, menu, nav, section, summary { display: block;}
a { color: inherit;  text-decoration: inherit;  cursor: inherit;}
a:active, a:focus { outline: none; }
input[type="button"], button, a { font-family: 'Microsoft YaHei', Verdana, Geneva, Arial, Helvetica, SimHei, sans-serif; }
body {font-family: 'Microsoft YaHei', Verdana, Geneva, Arial, Helvetica, SimHei, sans-serif;}

JS规范

  • JS 换行缩进：采用 4 空格
  • 结束行需添加分号;
  • jQuery变量要求首字符为 $, 尽量避免全局变量.
  • JS调试使用console.log()及console.dir()进行，避免使用弹出框，线上版需要注释所有调试代码
  • 库引入: 原则上仅引入jQuery库, 若需引入第三方库, 须与团队其他人员讨论决定
  • 命名语义化, 尽可能利用英文单词或其缩写;
  • 代码结构明了, 加适量注释. 提高函数重用率;
  • 注重与html分离, 减小reflow, 注重性能, 一个页面对应一个js文件.
    1
2
3
4
5
6
7

    // 使用闭包来解决全局变量污染的问题
(function(){
  // 对于事件的监听, 
  // 不要这么写 <a onclick=""/>  可以这么写
  $("selector").bind("click", function(e){
  });
})();

jQuery Plugin

  • IE对HTML5标签支持，以及浏览器特性检测：[Modernizr] & [html5shiv]
  • IE6 PNG 图片支持：[DD_belatedPNG]
  • 定制&统一 浏览器的滚动条样式：[jquery-scroll] & [Lionbars]
  • hover提示效果文字：[bootstrap-tooltips] & [tipsy]
  • 滚动条跟随nav效果：[bootstrap-scrollspy]
  • 提示冒泡文字：[grumble.js]
  • 导航栏过渡效果：[lavalamp]
  • 移动设备的滚动效果：[iscroll 4]
  • Mac OS Lion 风格的滚动条：[Lionbars]
  • 弹性SlideShow：[kwicks for jQuery]
  • 瀑布流：[isotope]
  • 抖动效果：[jQ shake]
  • LightBox：[fancyBox]
  • KenDo UI：[KenDo UI]
  • textarea自适应高度：[elastic]
  • 提示区域 & 提示层：[noty]
  • 浮动话题泡：[jQuery grumble]
  • 旋转进度：[jQuery Knob]
文章目录
  1. 1. 文件规范
  2. 2. 编辑器配置
  3. 3. HTML规范
    1. 3.1. 模板
    2. 3.2. 建议
      1. 3.2.1. 属性顺序
      2. 3.2.2. 实用为王
      3. 3.2.3. 减少标签的数量
      4. 3.2.4. JavaScript 生成的标签
      5. 3.2.5. 嵌套层级
  4. 4. CSS规范
    1. 4.1. 命名规范
    2. 4.2. 模板
    3. 4.3. 重构步骤约定
    4. 4.4. 建议
      1. 4.4.1. 声明顺序
      2. 4.4.2. 单行规则声明
    5. 4.5. CSS Reset
  5. 5. JS规范
    1. 5.1. jQuery Plugin