forked from mdo/code-guide
-
Notifications
You must be signed in to change notification settings - Fork 16
/
index.html
419 lines (385 loc) · 20.4 KB
/
index.html
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
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
---
layout: default
---
<div class="heading" id="toc">
<h2>目录</h2>
</div>
<div class="section toc">
<div class="col">
<h4><a href="#html">HTML</a></h4>
<ul>
<li><a href="#html-syntax">语法</a></li>
<li><a href="#html-doctype">HTML5 doctype</a></li>
<li><a href="#html-lang">Language 属性</a></li>
<li><a href="#html-encoding">字符编码</a></li>
<li><a href="#html-ie-compatibility-mode">Internet Explorer 兼容模式</a></li>
<li><a href="#html-style-script">引入 CSS 和 JavaScript</a></li>
<li><a href="#html-practicality">实用高于完美</a></li>
<li><a href="#html-attribute-order">属性顺序</a></li>
<li><a href="#html-boolean-attributes">Boolean 属性</a></li>
<li><a href="#html-reducing-markup">减少标签数量</a></li>
<li><a href="#html-javascript">JavaScript 生成的标签</a></li>
</ul>
</div>
<div class="col">
<h4><a href="#css">CSS</a></h4>
<ul>
<li><a href="#css-syntax">CSS 语法</a></li>
<li><a href="#css-declaration-order">声明顺序</a></li>
<li><a href="#css-media-queries">媒体查询位置</a></li>
<li><a href="#css-import">不要使用 @import</a></li>
<li><a href="#css-prefixed-properties">前缀属性</a></li>
<li><a href="#css-single-declarations">单条声明的声明块</a></li>
<li><a href="#css-shorthand">属性简写</a></li>
<li><a href="#css-nesting">LESS 和 SASS 中的嵌套</a></li>
<li><a href="#css-operators">LESS 和 SASS 中的运算符</a></li>
<li><a href="#css-comments">代码注释</a></li>
<li><a href="#css-classes">Class 命名</a></li>
<li><a href="#css-selectors">选择器</a></li>
<li><a href="#css-organization">代码组织</a></li>
</ul>
</div>
</div>
<div class="section" id="golden-rule">
<div class="col">
<h2>黄金法则</h2>
<p>始终同意并遵循规范的每一条内容 -- 可以是这里列出的，也可以是你自己的。不对之处，请随时指出，继续了解或贡献内容，请 <a href="https://github.com/mdo/code-guide/issues/new">open an issue on GitHub</a>。</p>
</div>
<div class="col">
<blockquote>
<p>不管有多少参与者，代码都应该像同一个人所写。</p>
</blockquote>
</div>
</div>
<div class="heading" id="html">
<h2>HTML</h2>
</div>
<div class="section" id="html-syntax">
<div class="col">
<h3>语法</h3>
<ul>
<li>使用两个空格的 soft tabs — 这是保证代码在各种环境下显示一致的唯一方式。</li>
<li>嵌套的节点应该缩进（两个空格）。</li>
<li>在属性上，使用双引号，不要使用单引号。</li>
<li>不好在自动闭合标签结尾处使用斜线 - <a href="http://dev.w3.org/html5/spec-author-view/syntax.html#syntax-start-tag">HTML5 规范</a> 指出他们是可选的。</li>
<li>不要忽略可选的关闭标签（例如，<code></li></code> 和 <code></body></code>）。</li>
</ul>
</div>
<div class="col">
{% highlight html %}{% include html/syntax.html %}{% endhighlight %}
</div>
</div>
<div class="section" id="html-doctype">
<div class="col">
<h3>HTML5 doctype</h3>
<p>在每个 HTML 页面开头使用这个简单地 doctype 来启用标准模式，使其每个浏览器中尽可能一致的展现。</p>
</div>
<div class="col">
{% highlight html %}{% include html/doctype.html %}{% endhighlight %}
</div>
</div>
<div class="section" id="html-lang">
<div class="col">
<h3>Language 属性</h3>
<p>根据 HTML5 规范：</p>
<blockquote>
<p>鼓励网站作者在 html 元素上指定 lang 属性，来指出页面的语言。这样做有助于语言合成工具来确定发音方式，以及帮助翻译工具决定使用的规则，等等。</p>
</blockquote>
<p>通过<a href="http://www.w3.org/html/wg/drafts/html/master/semantics.html#the-html-element">规范</a>中的 <code>lang</code> 属性了解更多相关内容。</p>
<p>前往 Sitepoint 查看 <a href="http://reference.sitepoint.com/html/lang-codes">language codes 列表</a>。</p>
</div>
<div class="col">
{% highlight html %}{% include html/lang.html %}{% endhighlight %}
</div>
</div>
<div class="section" id="html-encoding">
<div class="col">
<h3>字符编码</h3>
<p>通过声明一个明确的字符编码，让浏览器轻松、快速的确定适合网页内容的渲染方式。这样做之后，需要避免在 HTML 中出现字符实体，直接提供字符与文档一致的编码（通常是 UTF-8）。</p>
</div>
<div class="col">
{% highlight html %}{% include html/encoding.html %}{% endhighlight %}
</div>
</div>
<div class="section" id="html-ie-compatibility-mode">
<div class="col">
<h3>IE 兼容模式</h3>
<p>Internet Explorer 支持使用兼容性 <code><meta></code> 标签来指定使用什么版本的 IE 来渲染页面。如果不是特殊需要，通常通过 <strong>edge mode</strong> 来通知 IE 使用最新的兼容模式。</p>
<p>For more information, <a href="http://stackoverflow.com/questions/6771258/whats-the-difference-if-meta-http-equiv-x-ua-compatible-content-ie-edge-e">read this awesome Stack Overflow article</a>.</p>
</div>
<div class="col">
{% highlight html %}{% include html/ie-compatibility-mode.html %}{% endhighlight %}
</div>
</div>
<div class="section" id="html-style -script">
<div class="col">
<h3>引入 CSS 和 JavaScript</h3>
<p>根据 HTML5 规范, 通常在引入 CSS 和 JavaScript 时不需要指明 <code>type</code>，因为 <code>text/css</code> 和 <code>text/javascript</code> 分别是他们的默认值。</p>
<h4>HTML5 规范链接</h4>
<ul>
<li><a href="http://www.w3.org/TR/2011/WD-html5-20110525/semantics.html#the-link-element">使用 link</a></li>
<li><a href="http://www.w3.org/TR/2011/WD-html5-20110525/semantics.html#the-style-element">使用 style</a></li>
<li><a href="http://www.w3.org/TR/2011/WD-html5-20110525/scripting-1.html#the-script-element">使用 script</a></li>
</ul>
</div>
<div class="col">
{% highlight html %}{% include html/style-script.html %}{% endhighlight %}
</div>
</div>
<div class="section" id="html-practicality">
<div class="col">
<h3>实用高于完美</h3>
<p>尽量遵循 HTML 标准和语义，但是不应该以浪费实用性作为代价。任何时候都要用尽量小的复杂度和尽量少的标签来解决问题。</p>
</div>
</div>
<div class="section" id="html-attribute-order">
<div class="col">
<h3>属性顺序</h3>
<p>HTML 属性应该按照特定的顺序出现以保证易读性。</p>
<ul>
<li><code>class</code></li>
<li><code>id</code>, <code>name</code></li>
<li><code>data-*</code></li>
<li><code>src</code>, <code>for</code>, <code>type</code>, <code>href</code>, <code>value</code></li>
<li><code>title</code>, <code>alt</code></li>
<li><code>role</code>, <code>aria-*</code></li>
</ul>
<p>Classes 是为高可复用组件设计的，所以他们处在第一位。Ids 更加具体而且应该尽量少使用（例如, 页内书签），所以他们处在第二位。</p>
</div>
<div class="col">
{% highlight html %}{% include html/attribute-order.html %}{% endhighlight %}
</div>
</div>
<div class="section" id="html-boolean-attributes">
<div class="col">
<h3>Boolean 属性</h3>
<p>Boolean 属性指不需要声明取值的属性。XHTML 需要每个属性声明取值，但是 HTML5 并不需要。</p>
<p>了解更多内容，参考 <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/common-microsyntaxes.html#boolean-attributes">WhatWG section on boolean attributes</a>:</p>
<blockquote>
<p>一个元素中 Boolean 属性的存在表示取值 true，不存在则表示取值 false。</p>
</blockquote>
<p>如果你<em>必须</em>为属性添加<strong>并不需要的</strong>取值，参照 WhatWG 的指引:</p>
<blockquote>
<p>如果属性存在，他的取值必须是空字符串或者 [...] 属性的规范名称，不要在首尾包含空白字符。</p>
</blockquote>
<p><strong>简而言之，不要为 Boolean 属性添加取值。</strong></p>
</div>
<div class="col">
{% highlight html %}{% include html/boolean-attributes.html %}{% endhighlight %}
</div>
</div>
<div class="section" id="html-reducing-markup">
<div class="col">
<h3>减少标签数量</h3>
<p>在编写 HTML 代码时，需要尽量避免多余的父节点。很多时候，需要通过迭代和重构来使 HTML 变得更少。 参考下面的示例:</p>
</div>
<div class="col">
{% highlight html %}{% include html/reducing-markup.html %}{% endhighlight %}
</div>
</div>
<div class="section" id="html-javascript">
<div class="col">
<h3>JavaScript 生成标签</h3>
<p>在 JavaScript 文件中生成标签让内容变得更难查找，更难编辑，性能更差。应该尽量避免这种情况的出现。</p>
</div>
</div>
<div class="heading" id="css">
<h2>CSS</h2>
</div>
<div class="section" id="css-syntax">
<div class="col">
<h3>语法</h3>
<ul>
<li>使用两个空格的 soft tabs — 这是保证代码在各种环境下显示一致的唯一方式。</li>
<li>使用组合选择器时，保持每个独立的选择器占用一行。</li>
<li>为了代码的易读性，在每个声明的左括号前增加一个空格。</li>
<li>声明块的右括号应该另起一行。</li>
<li>每条声明 <code>:</code> 后应该插入一个空格。</li>
<li>每条声明应该只占用一行来保证错误报告更加准确。</li>
<li>所有声明应该以分号结尾。虽然最后一条声明后的分号是可选的，但是如果没有他，你的代码会更容易出错。</li>
<li>逗号分隔的取值，都应该在逗号之后增加一个空格。</li>
<li>不要在颜色值 <code>rgb()</code>, <code>rgba()</code>, <code>hsl()</code>, <code>hsla()</code>, 和 <code>rect()</code> <em>中</em>增加空格</li>
<li>不要在属性取值或者颜色参数前面添加不必要的 0 (比如，使用 <code>.5</code> 替代 <code>0.5</code> 和 <code>-.5px</code> 替代 <code>0.5px</code>)。</li>
<li>所有的十六进制值都应该使用小写字母，例如 <code>#fff</code>。因为小写字母有更多样的外形，在浏览文档时，他们能够更轻松的被区分开来。</li>
<li>尽可能使用短的十六进制数值，例如使用 <code>#fff</code> 替代 <code>#ffffff</code>。</li>
<li>为选择器中得属性取值添加引号，例如 <code>input[type="text"]</code>。 <a href="http://mathiasbynens.be/notes/unquoted-attribute-values#css">他们只在某些情况下可有可无</a>，所以都使用引号可以增加一致性。</li>
<li>不要为 0 指明单位，比如使用 <code>margin: 0;</code> 而不是 <code>margin: 0px;</code>。</li>
</ul>
<p>对这里提到的规则有问题吗？参考 Wikipedia 中的<a href="http://en.wikipedia.org/wiki/Cascading_Style_Sheets#Syntax"> CSS 语法部分</a>。</p>
</div>
<div class="col">
{% highlight css %}{% include css/syntax.css %}{% endhighlight %}
</div>
</div>
<div class="section" id="css-declaration-order">
<div class="col">
<h3>声明顺序</h3>
<p>相关的属性声明应该以下面的顺序分组处理：</p>
<ol>
<li>Positioning</li>
<li>Box model 盒模型</li>
<li>Typographic 排版</li>
<li>Visual 外观</li>
</ol>
<p>Positioning 处在第一位，因为他可以使一个元素脱离正常文本流，并且覆盖盒模型相关的样式。盒模型紧跟其后，因为他决定了一个组件的大小和位置。</p>
<p>其他属性只在组件 <em>内部</em> 起作用或者不会对前面两种情况的结果产生影响，所以他们排在后面。</p>
<p>关于完整的属性以及他们的顺序，请参考 <a href="http://twitter.github.com/recess">Recess</a>。</p>
</div>
<div class="col">
{% highlight css %}{% include css/declaration-order.css %}{% endhighlight %}
</div>
</div>
<div class="section" id="css-media-queries">
<div class="col">
<h3>媒体查询位置</h3>
<p>尽量将媒体查询的位置靠近他们相关的规则。不要将他们一起放到一个独立的样式文件中，或者丢在文档的最底部。这样做只会让大家以后更容易忘记他们。这里是一个典型的案例。</p>
</div>
<div class="col">
{% highlight css %}{% include css/media-queries.css %}{% endhighlight %}
</div>
</div>
<div class="section" id="css-import">
<div class="col">
<h3>不要使用 <code>@import</code></h3>
<p>与 <code><link></code> 相比, <code>@import</code> 更慢，需要额外的页面请求，并且可能引发其他的意想不到的问题。应该避免使用他们，而选择其他的方案：</p>
<ul>
<li>使用多个 <code><link></code> 元素</li>
<li>使用 CSS 预处理器例如 Sass 或 Less 将样式编译到一个文件中</li>
<li>使用 Rails, Jekyll 或其他环境提供的功能，来合并 CSS 文件。</li>
</ul>
<p>了解更多信息, 参照 Steve Souders 的<a href="http://www.stevesouders.com/blog/2009/04/09/dont-use-import/">这篇文章</a>。</p>
</div>
<div class="col">
{% highlight html %}{% include css/import.html %}{% endhighlight %}
</div>
</div>
<div class="section" id="css-prefixed-properties">
<div class="col">
<h3>前缀属性</h3>
<p>当使用厂商前缀属性时，通过缩进使取值垂直对齐以便多行编辑。</p>
<p>在 Textmate 中，使用 <strong>Text → Edit Each Line in Selection</strong> (⌃⌘A)。 在 Sublime Text 2 中， 使用 <strong>Selection → Add Previous Line</strong> (⌃⇧↑) 和 <strong>Selection → Add Next Line</strong> (⌃⇧↓)。</p>
</div>
<div class="col">
{% highlight css %}{% include css/prefixed-properties.css %}{% endhighlight %}
</div>
</div>
<div class="section" id="css-single-declarations">
<div class="col">
<h3>单条声明的声明块</h3>
<p>在一个声明块中<strong>只包含一条声明</strong>的情况下，为了易读性和快速编辑可以考虑移除其中的换行。所有包含多条声明的声明块应该分为多行。</p>
<p>这样做的关键因素是错误检测 - 例如，一个 CSS 验证程序显示你在 183 行有一个语法错误,如果是一个单条声明的行，那就是他了。在多个声明的情况下，你必须为哪里出错了费下脑子。</p>
</div>
<div class="col">
{% highlight css %}{% include css/single-declarations.css %}{% endhighlight %}
</div>
</div>
<div class="section" id="css-shorthand">
<div class="col">
<h3>属性简写</h3>
<p>坚持限制属性取值简写的使用，属性简写需要你必须显式设置所有取值。常见的属性简写滥用包括:</p>
<ul>
<li><code>padding</code></li>
<li><code>margin</code></li>
<li><code>font</code></li>
<li><code>background</code></li>
<li><code>border</code></li>
<li><code>border-radius</code></li>
</ul>
<p>大多数情况下，我们并不需要设置属性简写中包含的所有值。例如，HTML 头部只设置上下的 margin，所以如果需要，只设置这两个值。过度使用属性简写往往会导致更混乱的代码，其中包含不必要的重写和意想不到的副作用。</p>
<p>Mozilla Developer Network 有一篇对不熟悉属性简写及其行为的人来说很棒的关于 <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties">shorthand properties</a> 的文章。</p>
</div>
<div class="col">
{% highlight css %}{% include css/shorthand.css %}{% endhighlight %}
</div>
</div>
<div class="section" id="css-nesting">
<div class="col">
<h3>LESS 和 SASS 中的嵌套</h3>
<p>避免不必要的嵌套。可以进行嵌套，不意味着你应该这样做。只有在需要给父元素增加样式并且同时存在多个子元素时才需要考虑嵌套。</p>
</div>
<div class="col">
{% highlight scss %}{% include css/nesting.scss %}{% endhighlight %}
</div>
</div>
<div class="section" id="css-operators">
<div class="col">
<h3>LESS 和 SASS 中的运算符</h3>
<p>为了提高代码可读性，在数学运算外增加括号，并且在取值，变量和运算符之间增加空格。</p>
</div>
<div class="col">
{% highlight scss %}{% include css/operators.scss %}{% endhighlight %}
</div>
</div>
<div class="section" id="css-comments">
<div class="col">
<h3>代码注释</h3>
<p>代码是由人来编写和维护的。保证你的代码是描述性的，包含好的注释，并且容易被他人理解。好的代码注释传达上下文和目标。不要简单地重申组件或者 class 名称。</p>
<p>Be sure to write in complete sentences or larger comments and succinct phrases for general notes.</p>
</div>
<div class="col">
{% highlight css %}{% include css/comments.css %}{% endhighlight %}
</div>
</div>
<div class="section" id="css-classes">
<div class="col">
<h3>Class 命名</h3>
<ul>
<li>保持 Class 命名为全小写，可以使用短划线（不要使用下划线和 camelCase 命名）。短划线应该作为相关类的自然间断。(例如，<code>.btn</code> 和 <code>.btn-danger</code>)。</li>
<li>避免过度使用简写。<code>.btn</code> 可以很好地描述 <em>button</em>，但是 <code>.s</code> 不能代表任何元素。</li>
<li>Class 的命名应该尽量短，也要尽量明确。</li>
<li>使用有意义的名称；使用结构化或者作用目标相关，而不是抽象的名称。</li>
<li>命名时使用最近的父节点或者父 class 作为前缀。</li>
<li>使用 <code>.js-*</code> classes 来表示行为(相对于样式)，但是不要在 CSS 中定义这些 classes。</li>
</ul>
<p>这些规则在创建 Sass 和 Less 变量名时同样有用。</p>
</div>
<div class="col">
{% highlight css %}{% include css/class-names.css %}{% endhighlight %}
</div>
</div>
<div class="section" id="css-selectors">
<div class="col">
<h3>选择器</h3>
<ul>
<li>使用 classes 而不是通用元素标签来优化渲染性能。</li>
<li>避免在经常出现的组件中使用一些属性选择器 (例如，<code>[class^="..."]</code>)。浏览器性能会受到这些情况的影响。</li>
<li>减少选择器的长度，每个组合选择器选择器的条目应该尽量控制在 3 个以内。</li>
<li><strong>只</strong>在必要的情况下使用后代选择器 (例如，没有使用带前缀 classes 的情况).</li>
</ul>
<p>扩展阅读:</p>
<ul>
<li><a href="http://markdotto.com/2012/02/16/scope-css-classes-with-prefixes/">Scope CSS classes with prefixes</a></li>
<li><a href="http://markdotto.com/2012/03/02/stop-the-cascade/">Stop the cascade</a></li>
</ul>
</div>
<div class="col">
{% highlight css %}{% include css/selectors.css %}{% endhighlight %}
</div>
</div>
<div class="section" id="css-organization">
<div class="col">
<h3>代码组织</h3>
<ul>
<li>以组件为单位组织代码。</li>
<li>制定一个一致的注释层级结构。</li>
<li>使用一致的空白来分割代码块，这样做在查看大的文档时更有优势。</li>
<li>当使用多个 CSS 文件时，通过组件而不是页面来区分他们。页面会被重新排列组合，而组件是可以移动的。</li>
</ul>
</div>
<div class="col">
{% highlight css %}{% include css/organization-comments.css %}{% endhighlight %}
</div>
</div>
<div class="section" id="css-editor-prefs">
<div class="col">
<h3>编辑器配置</h3>
<p>根据以下的设置来配置你的编辑器，来避免常见的代码不一致和丑陋的 diffs。</p>
<ul>
<li>使用两个空格的 soft-tabs。</li>
<li>在保存时删除尾部的空白字符。</li>
<li>设置文件编码为 UTF-8。</li>
<li>在文件结尾添加一个空白行。</li>
</ul>
<p>参照文档，将这些设置应用到项目的 <code>.editorconfig</code> 文件。 例如，<a href="https://github.com/twbs/bootstrap/blob/master/.editorconfig">Bootstrap 中的 <code>.editorconfig</code> 文件</a>。 通过 <a href="http://editorconfig.org">关于 EditorConfig</a> 了解更多内容。</p>
</div>
</div>