Kai Soong

HTML/CSS ​

缩进 ​

每次缩进两个空格或者一个 Tab 制表符（一个 Tab 通过.editorconfig设置为 2 个空格）。

不要混合使用空格和Tab制表符。

::: codeStyle bad

html
<ul>
<li>Fantastic</li>
<li>Great</li>
</ul>

<style>
.example {
color: blue;
}
</style>

:::

::: codeStyle good

html
<ul>
  <li>Fantastic</li>
  <li>Great</li>
</ul>

<style>
  .example {
    color: blue;
  }
</style>

:::

大小写 ​

仅使用小写

HTML element 名称, 属性, 属性值 (除了 text/CDATA), CSS 选择器, 属性, 和属性值 (除了字符串).

::: codeStyle bad

html
<A HREF="/">Home</A>

<style>
  color: #E5E5E5;
</style>

:::

::: codeStyle good

html
<a href="/">Home</a>

<style>
  color: #e5e5e5;
</style>

:::

尾随空格 ​

删除不必要的空格

尾随空格是不必要的，并且会使差异复杂化。

::: codeStyle bad

html
<p>What? </p>

:::

::: codeStyle good

html
<p>What?</p>

:::

编码 ​

使用 UTF-8 编码

确保编辑器使用 UTF-8 作为字符编码，不使用字节顺序标记。

通过指定 HTML 模板和文档中的编码。不要指定样式表的编码，因为它们假设是 UTF-8。(关于编码以及何时以及如何指定它们的更多信息可以在处理 HTML 和 CSS 中的字符编码中找到。)

注释 ​

在必要的时候需要写注释，如: 逻辑复杂、结构复杂时候

TODO ​

用 TODO 标记待办事项和行动项目。

只使用关键字 TODO 来突出显示 TODO，而不是其他常见的格式，如@@。

在括号中添加联系人(用户名或邮件列表)，格式与 TODO(联系人)相同。

在冒号后添加操作项，如 TODO:操作项。

::: codeStyle good

html
<!-- TODO(songle): revisit centering -->
<center>Test</center>

<!-- TODO(songle): remove optional tags -->
<ul>
  <li>Apples</li>
  <li>Oranges</li>
</ul>

:::

自闭合标签 ​

自闭合标签尾部加/

常见的自闭合标签: <meta />、<link />、<br />、<hr />、<img />、<input />

::: codeStyle bad

html
<br>
<hr>

:::

::: codeStyle good

html
<br />
<hr />

:::

语义化 ​

根据 HTML 的用途使用它。

将元素(有时被错误地称为“标签”)用于创建它们的目的。例如，使用 heading 元素作为标题，使用 p 元素作为段落，使用 a 元素作为锚，等等。

根据目的使用 HTML 对于可访问性、重用性和代码效率非常重要。

::: codeStyle bad

html
<div onclick="goToRecommendations();">All recommendations</div>

:::

::: codeStyle good

html
<a href="recommendations/">All recommendations</a>

:::

关注点分离 ​

分离结构、表示和行为。

严格地将结构(标记)、表示(样式)和行为(脚本)分开，并尽量将三者之间的交互保持在绝对最小。

也就是说，确保文档和模板只包含 HTML 和仅用于结构目的的 HTML。将所有表示的内容移到样式表中，将行为的内容移到脚本中。

此外，通过从文档和模板中链接尽可能少的样式表和脚本，使联系区域尽可能小。

从维护的角度来看，将结构、表示和行为分离非常重要。更改 HTML 文档和模板总是比更新样式表和脚本更昂贵。

::: codeStyle bad

html
<h1 style="font-size: 1em;">HTML sucks</h1>

:::

::: codeStyle good

html
<h1 class="title">HTML sucks</h1>

<style>
  .title {
    font-size: 1em;
  }
</style>

:::

HTML 引号 ​

当引用属性值时，使用双引号。

使用双引号("")而不是单引号(")包围属性值。

::: codeStyle bad

html
<a class='maia-button maia-button-secondary'>Sign in</a>

:::

::: codeStyle good

html
<a class="maia-button maia-button-secondary">Sign in</a>

:::

Class 与 ID ​

class 应以功能或内容命名，不以表现形式命名

class 与 id 单词字母小写，多个单词组成时，采用中划线-分隔

使用唯一的 id 作为 Javascript hook, 同时避免创建无样式信息的 class

::: codeStyle bad

html
<div class="j-hook left contentWrapper"></div>

<div class="page_demo"></div>

:::

::: codeStyle good

html
<div id="j-hook" class="sidebar content-wrapper"></div>

<div class="page-demo"></div>

:::

属性顺序 ​

HTML 属性应该按照特定的顺序出现以保证易读性。

  1. id
  2. class
  3. name
  4. data-xxx
  5. src, for, type, href
  6. title, alt
  7. aria-xxx, role
  8. event

HTML 嵌套 ​

a标签不允许嵌套div这种约束属于语义嵌套约束，与之区别的约束还有严格嵌套约束，比如a不允许嵌套a。

严格嵌套约束在所有的浏览器下都不被允许，而语义嵌套约束，浏览器大多会容错处理，生成的文档树可能相互不太一样。

语义嵌套约束 ​

  • <li> 用于 <ul> 或 <ol> 下
  • <dd>, <dt> 用于 <dl> 下
  • <thead>, <tbody>, <tfoot>, <tr>, <td> 用于 <table> 下

严格嵌套约束 ​

inline-Level 元素，仅可以包含文本或其它 inline-Level 元素

  • <a>里不可以嵌套交互式元素<a>、<button>、<select>等
  • <p>里不可以嵌套块级元素<div>、<h1>~<h6>、<p>、<ul>/<ol>/<li>、<dl>/<dt>/<dd>、<form>等。

类型选择器 ​

避免使用类型选择器限定 ID 和类名。

除非必要(例如 helper 类)，不要将元素名与 id 或类一起使用。

由于性能原因，避免不必要的祖先选择器是有用的。

::: codeStyle bad

css
ul#example {
}
div.error {
}

:::

::: codeStyle good

css
#example {
}
.error {
}

:::

简写属性 ​

尽可能使用简写属性。

CSS 提供了各种应尽可能使用的简写属性(如字体)，即使在只有一个显式设置值的情况下也是如此。

使用简写属性有助于提高代码效率和易于理解。

::: codeStyle bad

css
.demo {
  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;
}

:::

::: codeStyle good

css
.demo {
  border-top: 0;
  font: 100%/1.6 palatino, georgia, serif;
  padding: 0 1em 2em;
}

:::

0 的单位 ​

在“0”值之后省略单元说明，除非需要。

除非必要，否则不要在 0 值后使用单位。

::: codeStyle good

css
.demo {
  flex: 0px; /* This flex-basis component requires a unit. */
  flex: 1 1 0px; /* Not ambiguous without the unit, but needed in IE11. */
  margin: 0;
  padding: 0;
}

:::

小数前边 0 ​

必须把 0 放在-1 和 1 之间的值或长度前面。

::: codeStyle bad

css
.demo {
  font-size: .8em;
}

:::

::: codeStyle good

css
.demo {
  font-size: 0.8em;
}

:::

十六进制计数法 ​

尽可能使用 6 个字符的十六进制表示法。不要使用 3 个字符

::: codeStyle bad

css
.demo {
  color: #ebc;
}

:::

::: codeStyle good

css
.demo {
  color: #eebbcc;
}

:::

CSS 属性声明顺序 ​

用字母表示声明。

将声明按字母顺序排列，以便以易于记忆和维护的方式实现代码的一致性。

为了排序，忽略特定于供应商的前缀。然而，对于特定的 CSS 属性，多个特定于供应商的前缀应该保持有序(例如-moz 前缀出现在-webkit 之前)。

::: codeStyle good

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

:::

CSS 声明结束符 ​

在每个声明后面使用分号。

为了一致性和可扩展性，每个声明都用分号结尾。

::: codeStyle bad

css
.test {
  display: block;
  height: 100px
}

:::

::: codeStyle good

css
.test {
  display: block;
  height: 100px;
}

:::

CSS 属性名结束符 ​

在属性名的冒号后面使用空格。

为了保持一致性，property 和 value 之间总是使用一个空格(property 和冒号之间不使用空格)。

::: codeStyle bad

css
h3 {
  font-weight:bold;
  color :#ccccc;
}

:::

::: codeStyle good

css
h3 {
  font-weight: bold;
  color: #ccccc;
}

:::

CSS 声明块分离 ​

在最后一个选择器和声明块之间使用一个空格。

在最后一个选择器和声明块的开始大括号之间总是使用一个空格。

在给定的规则中，左大括号应该与最后一个选择器在同一行。

::: codeStyle bad

css
/*  missing space */
#video{
  margin-top: 1em;
}

/*  unnecessary line break */
#video
{
  margin-top: 1em;
}

:::

::: codeStyle good

css
#video {
  margin-top: 1em;
}

:::

选择器和声明分离 ​

用新行分隔选择器和声明。

总是为每个选择器和声明开始一个新行。

::: codeStyle bad

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

:::

::: codeStyle good

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

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

:::

规则分离 ​

用新行分隔规则。

总是在规则之间放一个空行(两个换行符)。

::: codeStyle good

css
html {
  background: #fff;
}

body {
  margin: auto;
  width: 50%;
}

:::

CSS 引号 ​

对属性选择器和属性值使用单引号(")而不是双引号("")。

不要在 URI 值(url())中使用引号。

例外情况:如果您确实需要使用@charset 规则，请使用双引号——单引号是不允许的。

::: codeStyle bad

css
@import url("https://www.google.com/css/maia.css");

html {
  font-family: "open sans", arial, sans-serif;
}

:::

::: codeStyle good

css
@import url(https://www.google.com/css/maia.css);

html {
  font-family: 'open sans', arial, sans-serif;
}

:::