HTML
CSS
永远遵循同一套编码规范 -- 可以是这里列出的,也可以是你自己总结的。在任何时候遵循规范,可以是这里的规范或者你自己的编码规范。随时指出其中任何不正确地部分。继续了解此代码指引或者贡献内容,请 open an issue on GitHub 。
不管多少人同时参与编码,所有代码都应该看上去像是一个人编写的一样。
</li>
和 </body>
)。 <!DOCTYPE html> <html> <head> <title>Page title</title> </head> <body> <img src="images/company-logo.png" alt="Company"> <h1 class="hello-world">Hello, world!</h1> </body> </html>
在每个 HTML 页面开头使用这个简单地 doctype 来启用标准模式,使其每个浏览器中尽可能一致的展现。
<!DOCTYPE html> <html> <head> </head> </html>
根据 HTML5 规范:
鼓励网站作者在 html 元素上指定 lang 属性,来指出页面的语言。这样做会有助于语言合成工具来确定怎样发音,以及翻译工具决定使用的规则,等等。
通过 规范 中的 lang
属性了解更多相关内容。
Head to Sitepoint for a list of language codes .
<html lang="en-us"> <!-- ... --> </html>
通过声明一个明确的字符编码,让浏览器轻松、快速的确定适合网页内容的渲染方式。
<head> <meta charset="UTF-8"> </head>
Internet Explorer 支持使用兼容性 <meta>
标签来指定使用什么版本的 IE 来渲染页面。如果不是特殊需要,通常通过 edge mode 来通知 IE 使用最新的兼容模式。
For more information, read this awesome Stack Overflow article .
<meta http-equiv="X-UA-Compatible" content="IE=Edge">
根据 HTML5 规范, 通常在引入 CSS 和 JavaScript 时不需要指明 type
,因为 text/css
和 text/javascript
分别是他们的默认值。
<!-- External CSS --> <link rel="stylesheet" href="code-guide.css"> <!-- In-document CSS --> <style> /* ... */ </style> <!-- JavaScript --> <script src="code-guide.js"></script>
尽量遵循 HTML 标准和语义,但是不应该以浪费实用性作为代价。任何时候都要用尽量小的复杂度和尽量少的标签来解决问题。
HTML 属性应该按照特定的顺序出现以保证易读性。
class
id
, name
data-*
src
, for
, type
, href
title
, alt
aria-*
, role
Classes 是为高可复用组件设计的,所以他们处在第一位。Ids 更加具体而且应该尽量少使用(例如, 页内书签),所以他们处在第二位。
<a class="..." id="..." data-modal="toggle" href="#"> Example link </a> <input class="form-control" type="text"> <img src="..." alt="...">
Boolean 属性指不需要声明取值的属性。XHTML 需要每个属性声明取值,但是 HTML5 并不需要。
了解更多内容,参考 WhatWG section on boolean attributes :
一个元素中 Boolean 属性的存在表示取值 true,不存在则表示取值 false。
如果你 必须 为属性添加 并不需要的 取值,参照 WhatWG 的指引:
如果属性存在,他的取值必须是空字符串或者 [...] 属性的规范名称,不要在首尾包含空白字符。
<input type="text" disabled> <input type="checkbox" value="1" checked> <select> <option value="1" selected>1</option> </select>
在编写 HTML 代码时,需要尽量避免多余的父节点。很多时候,需要通过迭代和重构来使 HTML 变得更少。 参考下面的示例:
<!-- Not so great --> <span class="avatar"> <img src="..."> </span> <!-- Better --> <img class="avatar" src="...">
在 JavaScript 文件中生成标签让内容变得更难查找,更难编辑,性能更差。应该尽量避免这种情况的出现。
:
后应该插入一个空格。 rgb()
和 rgba()
中 增加空格,并且不要带有取值前面不必要的 0 (比如,使用 .5 替代 0.5)。 #fff
。因为小写字母有更多样的外形,在浏览文档时,他们能够更轻松的被区分开来。 #fff
替代 #ffffff
。 input[type="text"]
。 他们只在某些情况下可有可无 ,所以都使用引号可以增加一致性。 margin: 0;
而不是 margin: 0px;
。 对这里提到的规则有问题吗?参考 Wikipedia 中的 CSS 语法部分 。
/* Bad CSS */ .selector, .selector-secondary, .selector[type=text] { padding:15px; margin:0px 0px 15px; background-color:rgba(0, 0, 0, 0.5); box-shadow:0 1px 2px #CCC,inset 0 1px 0 #FFFFFF } /* Good CSS */ .selector, .selector-secondary, .selector[type="text"] { padding: 15px; margin: 0 0 15px; background-color: rgba(0,0,0,.5); box-shadow: 0 1px 2px #ccc, inset 0 1px 0 #fff; }
相关的属性声明应该以下面的顺序分组处理:
Positioning 处在第一位,因为他可以使一个元素脱离正常文本流,并且覆盖盒模型相关的样式。盒模型紧跟其后,因为他决定了一个组件的大小和位置。
其他属性只在组件 内部 起作用或者不会对前面两种情况的结果产生影响,所以他们排在后面。
关于完整的属性以及他们的顺序,请参考 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; }
尽量将媒体查询的位置靠近他们相关的规则。不要将他们一起放到一个独立的样式文件中,或者丢在文档的最底部。这样做只会让大家以后更容易忘记他们。这里是一个典型的案例。
.element { ... } .element-avatar { ... } .element-selected { ... } @media (min-width: 480px) { .element { ...} .element-avatar { ... } .element-selected { ... } }
@import
与 <link>
相比, @import
更慢,需要额外的页面请求,并且可能引发其他的意想不到的问题。应该避免使用他们,选择其他的方案:
<link>
元素 了解更多信息, 参照 Steve Souders 的 这篇文章 。
<!-- Use link elements --> <link rel="stylesheet" href="core.css"> <!-- Avoid @imports --> <style> @import url("more.css"); </style>
当使用厂商前缀属性时,通过缩进使取值垂直对齐以便多行编辑。
在 Textmate 中,使用 Text → Edit Each Line in Selection (⌃⌘A)。 在 Sublime Text 2 中, 使用 Selection → Add Previous Line (⌃⇧↑) 和 Selection → Add Next Line (⌃⇧↓)。
/* Prefixed properties */ .selector { -webkit-box-shadow: 0 1px 2px rgba(0,0,0,.15); box-shadow: 0 1px 2px rgba(0,0,0,.15); }
在一个声明块中 只包含一条声明 的情况下,为了易读性和快速编辑可以考虑移除其中的换行。所有包含多条声明的声明块应该分为多行。
这样做的关键因素是错误检测 - 例如,一个 CSS 验证程序显示你在 183 行有一个语法错误,如果是一个单条声明的行,那就是他了。在多个声明的情况下,你必须为哪里出错了费下脑子。
/* 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; }
坚持限制属性取值简写的使用,属性简写需要你必须显式设置所有取值。常见的属性简写滥用包括:
padding
margin
font
background
border
border-radius
大多数情况下,我们并不需要设置属性简写中包含的所有值。例如,HTML 头部只设置上下的 margin,所以如果需要,只设置这两个值。过度使用属性简写往往会导致更混乱的代码,其中包含不必要的重写和意想不到的副作用。
Mozilla Developer Network 有一篇对不熟悉属性简写及其行为的人来说很棒的关于 shorthand properties 的文章。
/* Bad example */ .element { margin: 0 0 10px; background: red; background: url("image.jpg"); border-radius: 3px 3px 0 0; } /* Good example */ .element { margin-bottom: 10px; background-color: red; background-image: url("image.jpg"); border-top-left-radius: 3px; border-top-right-radius: 3px; }
避免不必要的嵌套。可以进行嵌套,不意味着你应该这样做。只有在需要给父元素增加样式并且同时存在多个子元素时才需要考虑嵌套。
// Without nesting .table > thead > tr > th { … } .table > thead > tr > td { … } // With nesting .table > thead > tr { > th { … } > td { … } }
代码是由人来编写和维护的。保证你的代码是描述性的,包含好的注释,并且容易被他人理解。好的代码注释传达上下文和目标。不要简单地重申组件或者 class 名称。
Be sure to write in complete sentences or larger comments and succinct phrases for general notes.
/* Bad example */ /* Modal header */ .modal-header { ... } /* Good example */ /* Wrapping element for .modal-title and .modal-close */ .modal-header { ... }
.btn
和 .btn-danger
)。 .btn
可以很好地描述 button ,但是 .s
不能代表任何元素。 .js-*
classes 来表示行为(相对于样式),但是不要在 CSS 中包含这些 classes。 /* Bad example */ .t { ... } .red { ... } .header { ... } /* Good example */ .tweet { ... } .important { ... } .tweet-header { ... }
[class^="..."]
)。浏览器性能会受到这些情况的影响。 扩展阅读:
/* Bad example */ span { ... } .page-container #stream .stream-item .tweet .tweet-header .username { ... } .avatar { ... } /* Good example */ .avatar { ... } .tweet-header .username { ... } .tweet .avatar { ... }
/* * Component section heading */ .element { ... } /* * Component section heading * * Sometimes you need to include optional context for the entire component. Do that up here if it's important enough. */ .element { ... } /* Contextual sub-component or modifer */ .element-heading { ... }
根据以下的设置来配置你的编辑器,来避免常见的代码不一致和丑陋的 diffs。
参照文档,将这些设置应用到项目的 .editorconfig
文件。 例如, Bootstrap 中的 .editorconfig
文件 。 通过 关于 EditorConfig 了解更多内容。