前端规范

HTML/CSS部分（初稿）

写在前面

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

目录

  • 通用规范
  • 通用代码格式
  • 通用Meta格式
  • HTML规范
  • HTML代码格式
  • CSS规范
  • CSS代码格式

通用部分

通用规范

嵌入资源忽略协议类型

对于图片、媒体文件、样式文件、脚本的URL地址中忽略协议部分（https:, http:），除非该资源只能支持某一种协议类型。

原因：

  • 使URL地址可以根据当前页面的协议形式进行请求，避免出现https和http混合的内容。
    例子： https://mail.163.com/
  • 减少文件大小

<!-- Not recommended -->
<script src="http://www.exmaple.com/js/example.js"></script>

<!-- Recommended -->
<script src="//www.google.com/autotrack.js"></script>
              

/* Recommended */
.example {
  background: url(http://www.google.com/images/example);
}
/* Not recommended */
.example {
  background: url(//www.google.com/images/example);
}

通用代码格式

缩进

使用空格缩进，一次缩进两个空格

不要使用tab或者混合使用tab和space进行缩进


大小写

所有的代码小写，包括：

  • HTML元素名称、属性、属性值（text/CDATA除外）
  • CSS的选择器，属性，和属性值（字符串除外）

末尾空格

去除行尾无用空格

行尾空格容易造成文件差异比较时的混乱


<!-- Not recommended -->
<A HREF="/">Home</A>

<!-- Recommended -->
<img src="google.png" alt="Google">
              

/* Not recommended */
color: #E5E5E5;

/* Recommended */
color: #e5e5e5;

通用Meta规范

编码

使用UTF-8编码格式

  • 确保编辑器使用UTF-8编码格式，不要使用BOM（待议）
  • 在HTML模板和文档中，通过<meta charset="utf-8">声明编码格式
  • 不要特定样式表的编码格式，因为它默认为UTF-8

更多关于编码格式及如何声明的问题，参见Handling character encodings in HTML and CSS


注释（可选）

所有的代码小写，包括：

  • HTML元素名称、属性、属性值（text/CDATA除外）
  • CSS的选择器，属性，和属性值（字符串除外）

HTML部分

HTML规范

HTML有效性

验证HTML有效性，如标签闭合，重复ID，无效属性等问题

可以使用W3C HTML validator来进行验证


语义化

根据目的使用对应的HTML元素（常被错误的称呼为HTML标签
例如：标题使用标题元素，段落使用p元素，链接使用a元素等等


文档类型

使用HTML5的文档类型<!DOCTYPE html> （推荐使用HTML，对应的MIME类型为text/html。不推荐使用XHTML，对应的MIME类型为application/xhtml+xml，因为该类型缺少浏览器的支持，并且相较于HTML，会少了很多优化的空间） 并且对于HTML来说，不要关闭空元素，例如：使用<br>，而无需使用<br /> 


<!-- 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>
              


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

HTML规范

关注点分离

将结构（标记）、展示（样式）、行为（脚本）分离，并且尽量使这三者的交互减少到最小
保证文档和模板只包含HTML，并且HTML只作为页面结构的目的而使用，将所有的样式放入样式表，将所有的行为放入脚本中去
并且，在HTML模板中尽力减少外联样式和脚本的数量以保证三者的连接尽量简单
将样式和行为从结构中分离出来可提高代码的可维护性。因为修改HTML模板的代价远高于修改样式表和脚本。


多媒体兼容

对于图片、视频、canvas创建的动画对象等多媒体，提供替代的内容。
例如：对图片使用alt属性提供有意义的替代文字，对于视频音频，提供对应的字幕和标题。
例外：

  • 如果图片在页面中已经有了其他的文字解释，引入alt的内容会带来冗余
  • 该图片只是为了装饰性而使用，并且还无法使用CSS背景图片来替代

<!-- Not recommended -->
<!DOCTYPE html>
<title>HTML sucks</title>
<link rel="stylesheet" href="base.css" media="screen">
<link rel="stylesheet" href="grid.css" media="screen">
<link rel="stylesheet" href="print.css" media="print">
<h1 style="font-size: 1em;">HTML sucks</h1>
<p>I’ve read about this on a few sites but now I’m sure:
  <u>HTML is stupid!!1</u>
<center>I doing everything</center>

<!-- Recommended -->
<!DOCTYPE html>
<title>My first CSS-only redesign</title>
<link rel="stylesheet" href="default.css">
<h1>My first CSS-only redesign</h1>
<p>I’ve read
<p>It’s awesome!
              


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

HTML规范

HTML字符实体引用

不要使用HTML字符实体引用
只要团队中使用的文件和编辑器都设置为UTF-8，则没有必要使用&mdash;、&rdquo;、&#x263a;这样的实体引用
需要使用实体引用的情况有两种：

  • 在HTML中有特殊意义的字符，比如<、&
  • 控制符，或者空格

type属性

忽略样式表和脚本的type属性
HTML5规范中样式表和脚本的type属性默认分别为text/css和text/javascript。
对于老的浏览器，这么做也是可以的。
当然，如果样式表使用的不是CSS或者脚本使用的不是Javascript，则需要显示声明type属性 


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

HTML代码格式

通用格式

对于所有的block、list、table元素，必须新起一行，并且缩进其子元素
对于block、list、table的子节点，都需要缩进。
如果使用时碰到list的项之间出现空格的问题，可以折中地将所有li元素写在一行。代码检查会出现警告，而非错误。


引号使用

属性值使用双引号


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

CSS部分

CSS规范

CSS有效性

使用有效的CSS代码。
除非遇到特定的兼容性语法，如前缀、IE兼容语法等。
使用 W3C CSS validator测试有效性


类型选择器

避免使用类型选择器去限定ID和Class
除非有必要（例如使用Helper类时），不要将类型选择器与ID或Class同时使
减少不必要的祖先选择器对于性能来说 有所帮助。


CSS Hacks

避免使用UA检测和CSS Hack，优先尝试其他的解决方案
虽然使用UA检测或者特殊的CSS滤镜、Hack可以很方便地解决一些样式上的差异问题。但是为了编写和维护高效和可控的代码基础，这些方法只能作为最后的手段。
从项目的长远来看，如果轻易地给这些方法开绿灯，就会使得项目更加倾向于使用更多的这些方法，最终会导致项目代码完全无法维护。 


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

CSS规范

ID和Class命名

使用有意义或者通用的ID和Class命名。
ID和Class命名时最好能够表达出这一样式的目的，而不是使用表象的或者晦涩难懂的命名方式。
特定的或者能够表达出目的的命名容易理解而且不会轻易改变
通用的命名是为了那些没有特殊目的元素或者那些跟其相同的元素没有意义上差别的元素，他们就类似于Helper方法一样
使用通用的命名可以减少HTML代码改动的几率。

命名在保证易懂的前提下尽量简短
在能够描述清楚这一ID或Class时，尽力保持简短
这样命名ID和Class能够让代码更加易懂并提升代码效率


ID和Class分隔符

在ID和Class中使用-作为词语的分隔符
不要使用下划线或者驼峰等形式作为ID和Class的分隔形式，需要保持这种习惯，以提高代码的可读性和一致性。 


/* Not recommended: meaningless */
#yee-1901 {}
/* Not recommended: presentational */
.button-green {}
.clear {}
/* Recommended: specific */
#gallery {}
#login {}
.video {}
/* Recommended: generic */
.aux {}
.alt {}
/* Not recommended */
#navigation {}
.atr {}
/* Recommended */
#nav {}
.author {}
/* Not recommended: does not separate the words */
.demoimage {}
/* Not recommended: uses underscore instead of hyphen */
.error_status {}
/* Recommended */
#video-id {}
.ads-sample {}

CSS规范

属性简写 （待议）

尽可能使用属性简写
CSS提供了的某些简写形式（如font），就算只是显式设定其中一个值，也要使用缩写形式。
使用简写形式可以提高代码效率和可读性。


关于0精简

在属性值为0时，忽略单位，除非该单位是必须的。
当属性值在-1与1之间时，忽略前置的0


16进制精简

尽量使用3位16进制数更加短小简洁


/* 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;
              


/* Recommended */
margin: 0;
padding: 0;

font-size: .8em;
              


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

CSS代码格式

属性声明顺序

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

  • Positioning
  • Box model
  • Typographic
  • Visual

由于定位（positioning）可以从正常的文档流中移除元素，并且还能覆盖盒模型（box model）相关的样式，因此排在首位。盒模型排在第二位，因为它决定了组件的尺寸和位置。 其他属性只是影响组件的内部（inside）或者是不影响前两组属性，因此排在后面。 完整的属性列表及其排列顺序请参考 Recess。 


.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代码格式

CSS样式声明格式
  • 所有块级元素要进行缩进，增加层级能提高代码的可读性。
  • 属性名的冒号后需要加空格
  • 每个属性声明都要加分号，即使最后一个声明也不要省略
  • 在最后一个选择器和声明块的左侧花括号之间要有一个空格，且声明块左侧花括号必须和最后一个选择器同一行。
  • 每个选择器和声明都要新起一行
  • 在不同规则之间空一行

a:focus,
a:active {
  position: relative;
  top: 1px;
}

h1,
h2,
h3 {
  font-weight: normal;
  line-height: 1.2;
}

CSS代码格式

CSS冒号使用

属性选择器和属性值都使用单引号，不要给URI值（url()）加上任何引号 例外：如果你必须要使用@charset，可以使用双引号


/* 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;
}

写在最后

保持一致性！

在你修改一段代码之前，花几分钟看看这些代码的基本格式。
如果他们在所有的运算符前后都加了空格，那么你也应该加上。
如果代码的评论是用一圈#号围起来的，那么你的评论也该这么做。
制定并施行代码规范的目的在于，能建立一种通用的代码“语法”，
让人们能够专注于你的代码要表达什么，而不是怎么表达的。
我们在这里制订了全局的样式规范，让人们能够了解这一“语法”，
但如果你添加的代码与原有的代码差别很大，则要尽量注意保持与原有代码风格一致。

参考文档