Skip to content

Commit e5a9301

Browse files
guoyunheguoyunhe
committed
docs: group
1 parent ecb8cbc commit e5a9301

10 files changed

+243
-141
lines changed

‎docs/coding/1.html-style-guide.md

+11-6
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,9 @@
1+
---
2+
group: 代码规约
3+
---
4+
15
# HTML 编码规约
6+
27
> 注：本篇规约无配套的 Lint 工具包
38
49
## 1 文档
@@ -42,7 +47,7 @@
4247
- 1.3.1【推荐】使用 UTF-8 字符编码。
4348

4449
声明一个明确的字符编码，可以让浏览器更快速高效地确定适合网页内容的渲染方式。
45-
50+
4651
由于历史原因，不同浏览器采用了不同的字符编码。但对于新业务，如无特殊要求，统一使用 UTF-8 字符编码，以便统一。
4752

4853
在 HTML 中使用 `<meta charset="utf-8" />` 声明文档的编码方式：
@@ -54,9 +59,9 @@
5459
```
5560

5661
- 1.3.2【推荐】页面提供给移动设备使用时，需要设置 [viewport](https://drafts.csswg.org/css-device-adapt/#viewport-meta)。
57-
62+
5863
设置 viewport-fit 设置为“cover”来兼容 iPhone X 的刘海屏，[了解更多](https://webkit.org/blog/7929/designing-websites-for-iphone-x/) 。
59-
64+
6065

6166
```html
6267
<meta name="viewport" content="width=device-width, minimum-scale=1.0, viewport-fit=cover" />
@@ -88,7 +93,7 @@
8893
在 `<body></body>` 中指定外部样式表和嵌入式样式块可能会导致页面的重排和重绘，对页面的渲染造成影响。因此，一般情况下，CSS 应在 `<head></head>` 标签里引入，[了解更多](https://developer.yahoo.com/performance/rules.html#css_top)。
8994

9095
> 在 HTTP2（Chrome 浏览器 69 版本之后，Firefox 和 Edge）中可以在 body 中使用 link 标签引入样式文件，但不推荐在 body 中使用 `<style>` 标签的内联样式。**`<link rel="stylesheet">` 将会阻止后续内容的渲染，而不是整个页面**。
91-
96+
9297
除了基础库等必须要在 DOM 加载之前运行的 JavaScript 脚本，其他都在靠近 `body` 结束标签前引入，以防止出现页面渲染的阻塞，[了解更多](https://developer.yahoo.com/performance/rules.html#js_bottom)。
9398

9499

@@ -162,7 +167,7 @@
162167
### 2.1 缩进
163168

164169
- 2.1.1【推荐】统一使用 2 个空格缩进，不要使用 4 个空格或 tab 缩进。
165-
170+
166171
```html
167172
<!DOCTYPE html>
168173
<html>
@@ -181,7 +186,7 @@
181186
- 2.2.1【强制】在 HTML 注释代码中，不允许出现任何敏感信息。
182187

183188
常见的敏感信息包括：
184-
189+
185190
- 业务相关敏感信息，例如业务规则
186191
- 员工个人隐私信息，例如邮箱、手机、身份证号码
187192
- AK（accessKey id, accesskey secret）

‎docs/coding/2.css-style-guide.md

+13-9
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
---
2+
group: 代码规约
3+
---
4+
15
# CSS 编码规约
26

37
本规约涉及 CSS 及其预编译语言（Sass、Less）的编码风格和最佳实践，部分规则可通过 [stylelint](https://stylelint.io/) 工具落地。
@@ -11,7 +15,7 @@
1115
上图是一张符合规约要求编码风格的速览图，详细规则如下：
1216

1317
- 1.1.1【强制】所有声明都应该以分号结尾，不能省略。stylelint: [declaration-block-trailing-semicolon](https://stylelint.io/user-guide/rules/declaration-block-trailing-semicolon)
14-
18+
1519
虽然 CSS 语法中最后一条声明的分号是可选的，但是使用分号可以增加代码的一致性和易用性。
1620

1721
```css
@@ -42,7 +46,7 @@
4246
}
4347
```
4448

45-
- 1.1.3【推荐】选择器和 `{` 之间保留一个空格。stylelint: [block-opening-brace-space-before](https://stylelint.io/user-guide/rules/block-opening-brace-space-before)
49+
- 1.1.3【推荐】选择器和 `{` 之间保留一个空格。stylelint: [block-opening-brace-space-before](https://stylelint.io/user-guide/rules/block-opening-brace-space-before)
4650

4751
```css
4852
/* bad */
@@ -56,7 +60,7 @@
5660
}
5761
```
5862

59-
- 1.1.4【推荐】属性名和 `:` 之前无空格，`:` 和属性值之间保留一个空格。stylelint: [declaration-colon-space-after](https://stylelint.io/user-guide/rules/declaration-colon-space-after) [declaration-colon-space-before](https://stylelint.io/user-guide/rules/declaration-colon-space-before)
63+
- 1.1.4【推荐】属性名和 `:` 之前无空格，`:` 和属性值之间保留一个空格。stylelint: [declaration-colon-space-after](https://stylelint.io/user-guide/rules/declaration-colon-space-after) [declaration-colon-space-before](https://stylelint.io/user-guide/rules/declaration-colon-space-before)
6064

6165
```css
6266
/* bad */
@@ -180,7 +184,7 @@
180184
```
181185

182186
- 1.1.11【参考】使用多个选择器时，每个选择器应该单独成行。stylelint: [selector-list-comma-newline-after](https://stylelint.io/user-guide/rules/selector-list-comma-newline-after)
183-
187+
184188
```css
185189
/* bad */
186190
.selector, .selector-secondary, .selector-third {
@@ -234,7 +238,7 @@
234238
### 1.2 选择器
235239

236240
- 1.2.1【参考】不要使用 id 选择器。stylelint: [selector-max-id](https://stylelint.io/user-guide/rules/selector-max-id)
237-
241+
238242
id 会带来过高的[选择器优先级](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity)，使得后续很难进行样式覆盖（继而引发使用 `!important` 覆盖样式的恶性循环）。
239243

240244
```css
@@ -290,7 +294,7 @@
290294
> - 伪类（伪元素）选择器，比如 `a:hover`、`a::before`
291295
292296
### 1.3 属性和属性值
293-
297+
294298
- 1.3.1【推荐】使用尽可能短的十六进制值。stylelint: [color-hex-length](https://stylelint.io/user-guide/rules/color-hex-length)
295299

296300
```css
@@ -412,7 +416,7 @@
412416
```
413417

414418
更多 CSS 属性顺序参考如下列表：
415-
419+
416420
|第一组|第二组|第三组|第四组|第五组|第六组|第七组|
417421
|----|----|----|----|----|----|----|
418422
|content |box-sizing|background* |font*|opacity |unicode-bidi|transition*|
@@ -449,7 +453,7 @@
449453
- `border-radius`
450454

451455
使用简写属性时，需要显式地设置所有值。我们应该在真正需要设置所有值或大多数值时才使用简写属性。
452-
456+
453457
如果只是想设置某一个属性，则不应该使用简写属性：
454458

455459
```css
@@ -483,7 +487,7 @@
483487
## 2 Sass 和 Less
484488

485489
> 对于 CSS 而言，可以在新项目中尝试放弃使用 Sass、Less 这样的处理器语言，因为：
486-
>
490+
>
487491
>* 这些处理器语言是在一定历史条件下的产物，虽然这些产物在一定程度上提高开发者的开发效率，但不同的处理器语言也同时增加了项目的维护成本（特别是多人协作，多团队协作的时候）。
488492
>* 更建议使用 PostCSS 处理器，它类似于 CSS 中的 Babel，不但具备 Sass 和 Less 的功能，而且社区繁荣，同时还可以根据自己的需求扩展相关的插件。
489493
>* 随着 CSS 的一些新特性出现，Sass 和 Less 以往的优势也会慢慢消失。

‎docs/coding/3.javascript-style-guide.md

+6-3
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
---
2+
group: 代码规约
3+
---
14

25
# JavaScript 编码规约
36

@@ -6,7 +9,7 @@
69
JavaScript 编码规约主要包含编码风格、语言特性、注释、命名、配套工具等几个部分。本规约面向的 ECMAScript 语言版本是 ES6+，并提供了「关于 ES5」章节供仍在使用 ES5 的开发者查阅。
710

811
## 1 编码风格
9-
12+
1013
![示例代码标注图](https://img.alicdn.com/tfs/TB1IaB4hIVl614jSZKPXXaGjpXa-772-484.svg)
1114

1215
上图是一张符合规约要求编码风格的速览图，详细规则如下：
@@ -2397,7 +2400,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名
23972400
- **Null** 被计算为 **false**
23982401
- **布尔值** 被计算为 **布尔的值**
23992402
- **数字** 如果是 **+0、-0 或 NaN** 被计算为 **false**，否则为 **true**
2400-
- **字符串** 如果是空字符串 `''` 被计算为 **false**，否则为 **true**
2403+
- **字符串** 如果是空字符串 `''` 被计算为 **false**，否则为 **true**
24012404
24022405
```javascript
24032406
if ({}) { // => true
@@ -2492,7 +2495,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名
24922495
24932496
## 3 注释
24942497
2495-
> 注释的目的：提高代码的可读性，从而提高代码的可维护性
2498+
> 注释的目的：提高代码的可读性，从而提高代码的可维护性
24962499
> 注释的原则：如无必要，勿增注释；如有必要，尽量详尽
24972500
24982501
- 3.1【推荐】单行注释使用 //。

‎docs/coding/4.react-style-guide.md

+4
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
---
2+
group: 代码规约
3+
---
4+
15
# React 编码规约
26

37
## 1 编码风格

‎docs/coding/5.node-style-guide.md

+4
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
---
2+
group: 代码规约
3+
---
4+
15
# Node.js 编码规约
26

37
## 前言

0 commit comments

Comments
 (0)