Front-end Code Standards

编写本文档的主要驱动力是两方面: 1: 代码一致性 2: 最佳实践。通过保持代码风格和传统的一致性,我们可以减少遗留系统维护的负担,并降低未来系统崩溃的风险。而通过遵照最佳实践,我们能确保优化的页面加载、性能以及可维护的代码。

Common

总体原则

  1. 表现、内容和行为的分离
  2. 标记应该是结构良好、语义正确以及普遍合法
  3. Javascript应该起到渐进式增强用户体验的作用

样式规范

协议

省略图片、样式、脚本以及其他媒体文件 URL 的协议部分(http:,https:),除非文件在两种协议下都不可用。这种方案称为 protocol-relative URL,好处是无论你是使用 HTTPS 还是 HTTP 访问页面,浏览器都会以相同的协议请求页面中的资源,同时可以节省一部分字节。

1
2
<!-- Not recommended --> <script src="https://www.google.com/js/gweb/analytics/autotrack.js"></script>
<!-- Recommended --> <script src="//www.google.com/js/gweb/analytics/autotrack.js"></script>
1
2
/* Not recommended */ .example {  background: url("https://www.google.com/images/example"); }
/* Recommended */ .example { background: url("//www.google.com/images/example"); }

格式规范

缩进

一次缩进2个空格,不要使用 tab 或者混合 tab 和空格的缩进。

1
<ul>  <li>Fantastic  <li>Great </ul>

1
.example {  color: blue; }

大小写

以下都应该用小写:HTML 元素名称,属性,属性值(除非 text/CDATA),CSS 选择器,属性,属性值。

1
2
<!-- Not recommended --> <A HREF="/">Home</A>
<!-- Recommended --> <img src="google.png" alt="Google">

1
2
/* Not recommended */ color: #E5E5E5;
/* Recommended */ color: #e5e5e5;

结尾空格

结尾空格不仅多余,而且在比较代码时会更麻烦。

1
2
<!-- Not recommended --> <p>What?_
<!-- Recommended --> <p>Yes please.

元规范

编码

所有标记必须通过UTF-8编码传递,因为这种编码方式是对国际化最友好的。必须在HTTP的header和HTML文档的head部分都指定这种编码。在 HTML 中通过<meta charset="utf-8">指定编码方式,CSS 中不需要指定,因为默认是 UTF-8。

注释

使用注释来解释代码:包含的模块,功能以及优点。

TODO

用 TODO 来标记待办事项,而不是用一些其他的标记,像 @@。

1
<!-- TODO: remove optional tags --> <ul>  <li>Apples</li>  <li>Oranges</li> </ul>

HTML

总体原则

  • 段落分隔符要使用实际对应的 <p> 元素,而不是用多个<br>标签。
  • 在合适的条件下,充分利用 <dl> (定义列表)和 <blockquote> 标签。
  • 列表中的条目必须总是放置于 <ul><ol><dl>中,永远不要用一组 <div><p>来表示。
  • 给每个表单里的字段加上 <label> 标签,其中的 for 属性必须和对应的输入字段对应,这样用户就可以点击标签。同理,给标签加上 cursor: pointer; 样式也是明智的做法。
  • 不用使用输入字段中的 size 属性。该属性是和输入字段里文本的 font-size 相关的。应该使用CSS宽度。
  • 在某些闭合的 </div> 标签旁边加上一段html注释,说明这里闭合的是什么元素。这在有大量嵌套和缩进的情况下会很有用。
  • 不要把表格用于页面布局。
  • 在合适的条件下,利用 microformats 和/或者 Microdata ,具体说是 hCard 和 adr。
  • 在合适的条件下,利用 <thead><tbody><th>标签 (以及Scope属性)。
  • 对于页眉和标题,永远使用首字母大写格式。不要在标记中使用全部大写或小写的标题,而是应用CSS属性 text-transform: uppercase/lowercase

风格规范

文档类型

标记中必须总是使用合适的Doctype来指示浏览器触发标准模式. 永远要避免Quirks模式。HTML5特别好的一个方面就是它简化了Doctype需要的代码。无意义的属性被弃用了,DOCTYPE 声明也被显著地简化了。另外,也无需再用 CDATA 对内联JavaScript代码进行转义,而这在此之前为了让XHTML符合XML的严密性是必需的。
HTML 文档应使用 HTML5 的文档类型:<!DOCTYPE html>。
孤立标签无需封闭自身,<br> 不要写成 <br/>

HTML 正确性

尽可能使用正确的 HTML。

1
2
<!-- Not recommended --> <title>Test</title> <article>This is only a test.
<!-- Recommended --> <!DOCTYPE html> <meta charset="utf-8"> <title>Test</title> <article>This is only a test.</article>

语义化

根据使用场景选择正确的 HTML 元素(有时被错误的称为“标签”)。例如,使用 h1 元素创建标题,p 元素创建段落,a 元素创建链接等等。正确的使用 HTML 元素对于可访问性、可重用性以及编码效率都很重要。

1
2
<!-- Not recommended --> <div onclick="goToRecommendations();">All recommendations</div>
<!-- Recommended --> <a href="recommendations/">All recommendations</a>

多媒体元素降级

对于像图片、视频、canvas 动画等多媒体元素,确保提供其他可访问的内容。图片可以使用替代文本(alt),视频和音频可以使用文字版本。

1
2
<!-- Not recommended --> <img src="spreadsheet.png">
<!-- Recommended --> <img src="spreadsheet.png" alt="Spreadsheet screenshot.">

关注分离

HTML、CSS和JavaScript分离,确保相互耦合最小化。

实体引用

如果团队中文件和编辑器使用同样的编码方式,就没必要使用实体引用,如 —, ”,☺,除了一些在 HTML 中有特殊含义的字符(如 < 和 &)以及不可见的字符(如空格)。

1
2
<!-- Not recommended --> The currency symbol for the Euro is &ldquo;&eur;&rdquo;.
<!-- Recommended --> The currency symbol for the Euro is “€”.

type 属性

在引用样式表和脚本时,不要指定 type 属性,除非不是 CSS 或 JavaScript。因为 HTML5 中已经默认指定样式变的 type 是 text/css,脚本的type 是 text/javascript。

1
2
3
<!-- Not recommended --> <link rel="stylesheet" href="//www.google.com/css/maia.css"
type="text/css">

<!-- Recommended --> <link rel="stylesheet" href="//www.google.com/css/maia.css">

1
2
<!-- Not recommended --> <script src="//www.google.com/js/gweb/analytics/autotrack.js"  type="text/javascript"></script>
<!-- Recommended --> <script src="//www.google.com/js/gweb/analytics/autotrack.js"></script>

格式规范

HTML 引号

属性值用双引号。

1
2
<!-- Not recommended --> <a class='maia-button maia-button-secondary'>Sign in</a>
<!-- Recommended --> <a class="maia-button maia-button-secondary">Sign in</a>

风格规范

ID 和 Class 命名

使用有含义的 id 和 class 名称。

1
2
/* Not recommended: meaningless */#yee-1901 {}/* Not recommended: presentational */ .button-green {} .clear {}
/* Recommended: specific */#gallery {}#login {}.video {} /* Recommended: generic */ .aux {} .alt {}

ID 和 Class 命名风格

id 和 class 应该尽量简短,同时要容易理解。

1
2
/* Not recommended */#navigation {}.atr {}
/* Recommended */#nav {}.author {}

选择器

除非需要,否则不要在 id 或 class 前加元素名。无论是 ID 还是 class,对任何东西最好总是根据 它是什么 而不是 它看上去是什么样子 来命名。 比如一个页面上的特别提示的 class 名是 bigBlueText (大蓝字),可它的样式早就被改成红色小字体,这个名字就没意义了。使用更聪明的惯例如 noteText (提示文字)就好多了,因为即使视觉样式改变了,它也还是管用的。

1
2
/* Not recommended */ ul#example {}div.error {}
/* Recommended */#example {}.error {}

属性简写

尽量使用 CSS 中可以简写的属性 (如 font),可以提高编码效率以及代码可读性。

1
2
/* Not recommended */ border-top-style: none; font-family: palatino, georgia, serif; font-size: 100%; line-height: 1.6; padding-bottom: 2em; padding-left: 1em; padding-right: 1em; padding-top: 0;
/* Recommended */ border-top: 0; font: 100%/1.6 palatino, georgia, serif; padding: 0 1em 2em;

0 和单位

值为 0 时不用添加单位。

1
margin: 0; padding: 0;

开头的 0

值在 -1 和 1 之间时,不需要加 0。

1
font-size: .8em;

16进制表示法

1
2
/* Not recommended */ color: #eebbcc;
/* Recommended */ color: #ebc;

前缀

使用带前缀的命名空间可以防止命名冲突,同时提高代码可维护性。

1
2
/* Not recommended: does not separate the words “demo” and “image” */ .demoimage {} /* Not recommended: uses underscore instead of hyphen */ .error_status {}
/* Recommended */#video-id {}.ads-sample {}

CSS

网页的第二个组件就是在层叠样式表(CSS)中包含的表现信息。Web浏览器成功实现CSS后,整整一代web开发者对他们网站的外观和体验拥有了全部的控制权。正如网页信息在语义方面由 HTML 标记 描述, CSS 从表现方面则是通过对视觉属性的定义来描述网页。 CSS 的强大之处在于,这些属性可以混合并通过各种标示符匹配,它可以通过样式规则的分层(”层叠“)来控制页面的布局和视觉特征。

总体原则

  • 从外部文件加载CSS,尽可能减少文件数。加载标签必须放在文件的 HEAD 部分。
  • 用 LINK 标签加载,永远不要用@import。
  • 不要在文件中用内联式引入的样式,不管它是定义在样式标签里还是直接定义在元素上。这样会很难追踪样式规则。
  • 使用normalize.css 让渲染效果在不同浏览器中更一致
  • 使用类似 YUI fonts.css 的字体规格化文件
  • 定义样式的时候,对样式在页面只出现一次的元素用id,其他的用class
  • 理解 层叠和选择器的明确度 ,这样你就可以写出非常简洁且高效的代码。
  • 编写性能优化的选择器。尽可能避免使用开销大的CSS选择器。例如,避免 * 通配符选择器,也不要叠加限定条件到 ID 选择器(例如 div#myid)或 class 选择器(例如 table.results)上。这对于速度至上并包含了成千上万个DOM元素的web应用来说尤为重要。更多相关内容请参阅 MDN 上的这篇 《编写高效CSS》

格式规范

书写顺序

按照属性首字母顺序书写 CSS 易于阅读和维护,排序时忽略带有浏览器前缀的属性。

1
background: fuchsia; border: 1px solid; -moz-border-radius: 4px; -webkit-border-radius: 4px; border-radius: 4px; color: black; text-align: center; text-indent: 2em;

块级内容缩进

为了反映层级关系和提高可读性,块级内容都应缩进。

1
@media screen, projection {  html {    background: #fff;    color: #444;  } }

声明结束

每行 CSS 都应以分号结尾。

1
2
/* Not recommended */ .test {  display: block;  height: 100px }
/* Recommended */ .test { display: block; height: 100px; }

属性名结尾

属性名和值之间都应有一个空格。

1
2
/* Not recommended */ h3 {  font-weight:bold; }
/* Recommended */ h3 { font-weight: bold; }

声明样式块的分隔

在选择器和 {} 之间用空格隔开。

1
2
/* Not recommended: missing space */#video{  margin-top: 1em; } /* Not recommended: unnecessary line break */#video{  margin-top: 1em; }
/* Recommended */#video { margin-top: 1em; }

选择器分隔

每个选择器都另起一行。

1
2
/* Not recommended */ a:focus, a:active {  position: relative; top: 1px; }
/* Recommended */ h1, h2, h3 { font-weight: normal; line-height: 1.2; }

规则分隔

规则之间都用空行隔开。

1
html {  background: #fff;} body {  margin: auto;  width: 50%; }

字母排序

如果你对性能情有独钟,对CSS属性进行字母排序有利于在GZIP压缩中识别大量可重复的特征

伪类

伪类 使你能动态地修饰网页内容的样式。有些伪类从CSS1 (:visited, :hover等) 和 CSS2 (:first-child, :lang)那时候开始就有了。CSS3又往列表里加入了16个新的伪类,这些伪类对于动态地修饰网页内容的样式特别有用。 学习如何深度使用伪类

组合及属性选择器

组合选择器: 提供了为特定元素选择其后代元素、孩子元素或兄弟元素的快捷方式。
属性选择器: 适用于具有特定属性 和/或 特定值的元素。正则表达式的知识对属性选择大有帮助

明确度

浏览器会通过 计算选择器的明确度 来决定应用哪个CSS规则。如果两个选择器都适用于同样的元素,具有更高明确度的那个会胜出。
ID 选择器比属性选择器明确度高,class 选择器比任何数量的元素选择器明确度高。尽量使用 ID 选择器来提高明确度。有时候我们可能会想方设法给一个元素应用一条CSS规则,但用尽方法也不能如愿。这种情况有可能是因为我们使用的选择器比另外一个的明确度低,所以明确度高的另一个选择器里的属性就比我们想应用的选择器优先了。这种情况在更大或更复杂的样式表里更为常见。在小一些的项目里,通常这不是大问题。

计算明确度

当你在一个很大很复杂的样式表上干活的时候,知道如何计算选择器的明确度会有很大帮助,会节约你的时间,并让你的选择器更有效率。
明确度的计算方式是对你的CSS的各种组件计数,并用 (a,b,c,d) 格式表达出来。

  • 元素,伪元素: d = 1 – (0,0,0,1)
  • 类,伪类,属性: c = 1 – (0,0,1,0)
  • Id: b = 1 – (0,1,0,0)
  • 内联样式: a = 1 – (1,0,0,0)
    不过,也许使用现成的明确度计算器更好一些
  • 明确度计算器
  • 你应该了解的关于明确度的一些事
  • IE 明确度 bugs
    使用 !important 会覆盖掉所有的明确度,不管它有多高。因此我们倾向于避免使用它。大部分时候是没必要用它的。即使你需要覆盖某个你访问不到的样式表里的选择器,往往也会有其他的办法去覆盖。尽可能避免使用它

    像素 vs Em

    我们使用 px 作为定义 font size 的度量单位,因为它能提供对文本的绝对控制。我们知道为字体大小使用 em 单位一度很流行,这样可以解决 IE6 无法改变基于像素的文本大小的问题。不过,现在所有的主流浏览器(包括 IE7 和 IE8)都支持基于像素单位的文本大小 和/或 整页缩放。既然 IE6 被广泛认为已废弃,用像素定义文本尺寸更好。另外,无单位的 line-height 也应该优先考虑,因为它不会从父元素继承一个百分比值,而是基于 font-size 的一个乘数。
    1
    2
    /* Not recommended */ #selector {font-size: 0.813em; line-height: 1.25em;}
    /* Recommended */ #selector { font-size: 13px; line-height: 1.5; /* 13 * 1.5 = 19.5 ~ Rounds to 20px. */ }

IE Bugs

不可避免地,当所有其他浏览器看起来都正常工作的时候,各种版本的IE浏览器就会冒出一些莫名其妙的bug,让部署一拖再拖。虽然我们鼓励排除问题,产出无需打补丁就能在所有浏览器上运行的代码,有时候为了在样式表中使用CSS钩子,还是有必要用到CSS if IE 条件注释。从 paulirish.com 了解更多信息。

CSS 引号

属性选择器和属性值用单引号,URI 的值不需要引号。

1
2
/* Not recommended */@import url("//www.google.com/css/maia.css");html {  font-family: "open sans", arial, sans-serif; }
/* Recommended */@import url(//www.google.com/css/maia.css);html { font-family: 'open sans', arial, sans-serif; }

元规则

分段注释

用注释把 CSS 分成各个部分。

1
/* Header */#adw-header {}/* Footer */#adw-footer {}/* Gallery */ .adw-gallery {}

JavaScript

SEO

良好的web设计和开发的一个重要部分就是SEO 。要想确保一个网页不仅能让搜索引擎合适地索引到,而且能让那些只有有限的web能力的人访问到,结构良好的代码是其中的关键。

SEO最佳实践

易于索引

你必须使用语义化的标记,在关闭 Javascript 和 CSS 之后它仍然是可读和逻辑的。所有页面内容必须是HTML 形式;我们不希望使用iframe 或 Javascript 来加载初始的可索引内容。
所有链接都必须指向 HTML,这样既能被搜索引擎正确索引,也能让用户在新窗口或新标签中打开链接。

1
2
/* Not recommended */ <a href="javascript:loadPage(2);">
/* Recommended */ <a href="/shelf/jordan/page/2">

优化

每个页面的 title 标签应该突出目标关键字。每个页面的 title 应该是独特的。标题(h1,h2,等等)应该构成文档的轮廓并代表该页面最重要的关键字。URL 应该是人类可读的,其中包含主要的目标关键字

Flash和图片替换

总是为 flash 使用备选HTML 内容。所有广告促销图片应该使用基于 CSS 的替代图片而不仅仅设定 alt 属性。

Code Review

代码审查是确保系统质量和用户体验的正式流程中的基石。这涉及到召开一个由标记编写者、审查者和其他相关人员参加的会议,在会上提交有关材料,产生后续的代码修改要求。简单地说,我们鼓励进行代码审查,磨刀不误砍柴工嘛。

  • 所有页面代码,相关的服务器端引用,CSS 和Javascript。这些必须有完整注释,左侧列出行号,在每个打印页的页脚标明文件/页面名称。
  • 每个模板的截屏
  • 如果适用,标明模板对应的URL
  • 项目支持的浏览器和平台的清单
  • 已知问题和关注领域的清单

Link

文章目录
  1. 1. Common
    1. 1.1. 总体原则
    2. 1.2. 样式规范
      1. 1.2.1. 协议
    3. 1.3. 格式规范
      1. 1.3.1. 缩进
      2. 1.3.2. 大小写
      3. 1.3.3. 结尾空格
    4. 1.4. 元规范
      1. 1.4.1. 编码
      2. 1.4.2. 注释
      3. 1.4.3. TODO
  2. 2. HTML
    1. 2.1. 总体原则
    2. 2.2. 风格规范
      1. 2.2.1. 文档类型
      2. 2.2.2. HTML 正确性
      3. 2.2.3. 语义化
      4. 2.2.4. 多媒体元素降级
      5. 2.2.5. 关注分离
      6. 2.2.6. 实体引用
      7. 2.2.7. type 属性
    3. 2.3. 格式规范
      1. 2.3.1. HTML 引号
    4. 2.4. 风格规范
      1. 2.4.1. ID 和 Class 命名
      2. 2.4.2. ID 和 Class 命名风格
      3. 2.4.3. 选择器
      4. 2.4.4. 属性简写
      5. 2.4.5. 0 和单位
      6. 2.4.6. 开头的 0
      7. 2.4.7. 16进制表示法
      8. 2.4.8. 前缀
  3. 3. CSS
    1. 3.1. 总体原则
    2. 3.2. 格式规范
      1. 3.2.1. 书写顺序
      2. 3.2.2. 块级内容缩进
      3. 3.2.3. 声明结束
      4. 3.2.4. 属性名结尾
      5. 3.2.5. 声明样式块的分隔
      6. 3.2.6. 选择器分隔
      7. 3.2.7. 规则分隔
      8. 3.2.8. 字母排序
      9. 3.2.9. 伪类
      10. 3.2.10. 组合及属性选择器
      11. 3.2.11. 明确度
        1. 3.2.11.1. 计算明确度
      12. 3.2.12. 像素 vs Em
      13. 3.2.13. IE Bugs
      14. 3.2.14. CSS 引号
    3. 3.3. 元规则
      1. 3.3.1. 分段注释
  4. 4. JavaScript
  5. 5. SEO
    1. 5.1. SEO最佳实践
    2. 5.2. 易于索引
    3. 5.3. 优化
    4. 5.4. Flash和图片替换
  6. 6. Code Review
  7. 7. Link