前端编码规范

Posted 2022-11-25 web-panpan

Git 相关

代码提交规范

关于 Git 的 commit， 描述信息务必要准确描述这次代码改动所做的事情。

在此基础之上，提交代码时应遵守以下写法, 这也是开源社区较为推崇的一种写法, 最早从 Angular 社区传播开来. 格式为 `<type>(<scope>): <subject>`， 例如:

• feat：新功能（feature）
• fix：修补 bug
• style： 格式（比如：空格，空行的删除，log 的增删等，注释相关）
• docs：文档（documentation）
• refactor：性能或结构上的优化，并未带来功能的逻辑变化
• chore：构建过程或辅助工具的变动
• deploy: 上线部署（比如需要提交在本地 build 的资源等）
• test：增加测试

三个部分中 *type* 和 *subject* 必不可少，*scope* 根据实际情况来。如果某个 Git 仓库包含了几个大业务块，而我们的 commit 往往只是其中一个业务块中的一部分需求，这个情况下将 scope 补充上较好。

举个例子：

```
$ git commit -m "feat: add a new feature in button component"

$ git commit -m "feat(button): add a new feature"
```

创建 GIt 项目规范

关于 git 库创建的*标题*，*描述*，*README.md*，每一块信息都务必填写准确，README.md 要做到能完善描述整个项目，原则上对于一个从未接触过项目的同学，在看完 REAME.md 之后即可对项目有一个了解，不允许留白，同时也不要保持脚手架生成项目时的默认 README.md 内容，务必对其做出恰当的修改。

html相关

1.[强制] 使用 2 个空格做为一个缩进层级

2.[建议] 每行不得超过 120 个字符

过长的代码不容易阅读与维护。但是考虑到 HTML 的特殊性，不做硬性要求。

3.[强制] class 必须全字母小写，单词间以 - 分隔；必须代表相应模块的功能或内容，不得以样式信息进行命名。

4.[强制] 元素 id 必须保证页面唯一。

5.[建议] id 建议单词全字母小写，单词间以 - 分隔。

6.[强制] 同一页面，应避免使用相同的 name 与 id。

IE 浏览器会混淆元素的 id 和 name 属性， document.getElementById 可能获得不期望的元素。所以在对元素的 id 与 name 属性的命名需要非常小心。

7.[强制] 标签名必须使用小写字母

8.[强制] 对于无需自闭合的标签不允许自闭合。

常见无需自闭合标签有：input、br、img、hr 等。

9.[强制] 标签使用必须符合标签嵌套规则。

比如 div 不得置于 p 中，tbody 必须置于  table 中。

10.[建议] HTML 标签的使用应该遵循标签的语义。

常见的标签语义：

• p-段落
• h1，h2，h3，h4，h5，h6-层级标题
• strong，em-强调
• ins-插入
• del-删除
• abbr-缩写
• code-代码标识
• cite-引用来源作品的标题
• q-引用
• blockquote-一段或长篇引用
• ul-无序列表
• ol-有序列表
• dl，dt，dd-定义列表

11.[建议] 标签的使用应尽量简洁，减少不必要的标签。

12.[强制] 属性名必须小写；属性值必须使用双引号包围。

13.[建议] 自定义属性建议以 xxx- 为前缀，推荐使用 data-。

使用前缀有助于区分自定义属性和标准定义的属性。

14.[强制] 使用 HTML5 的 doctype 来启用标准模式，建议使用大写的 DOCTYPE。

15.[建议] 在 html 标签上设置正确的 lang 属性。

有助于提高页面的可访问性，如：让语音合成工具确定其所应该采用的发音，令翻译工具确定其翻译语言等。

16.[强制] 引入 CSS 时必须指明 ref="styleshet"。

如果不指明会导致样式失效。

17.[建议] 在 head 中引入页面需要的所有 css 资源。

在页面渲染的过程中，新的 css 可能导致元素的样式重新计算和绘制。

18.[建议] JavaScript 应当放在页面末尾，或采用异步加载。

将 script 放在页面中间将阻断页面渲染。

19.[建议] 若页面需要支持移动设备，需指定页面的 viewport。

viewport meta tag 可以设置可视区域的宽度和初始缩放大小，避免在移动设备上出现页面展示不正常。

20.[强制] 禁止 img 和 iframe 的 src 取值为空。

src 取值为空，会导致重新加载当前页面，直至加载失败，增加首屏渲染时间。

CSS 相关

1.[强制] class 名称应尽可能短，并且意义明确。

2.[建议] 基于最近的父 class 或者基本 class 作为新 class 的前缀。

3.[建议] 使用 .js-xxx 的 class 来标识行为，并且不要给这些 class 写有任何样式。

4.[强制] 尽量减少选择器的嵌套层级，不要超过 4 层。

5.[强制] css 提供了各种简写属性，使用简写属性对于代码效率和可读性是很有用的。

6.[建议] 不要在0 值后面使用单位。

7.[建议] 颜色使用 16 进制表示，在可能的情况下，可以进行缩写，比如：#F66。

8.[强制] 为了保证更好的可读性，应该遵循以下声明顺序：

• 定位：position | z-index | top | right | bottom | left
• 布局：display | float | overflow
• 尺寸：width | height | min-width | min-height | max-width | max-height
• 外边距：margin | margin-top | margin-bottom | margin-left | margin-right
• 内边距：padding | padding-top | padding-bottom | padding-left | padding-right
• 边框：border | border-top | border-bottom | border-right | border-left | border-radius | border-image | box-shadow
• 背景：background | background-color | background-image | background-size | background-repeat | background-position 
• 颜色：color | opacity
• 字体：font | font-size | font-weight | font-family
• 文本：text-align | line-height | white-space | word-break | letter-spacing | vertical-align
• 变换、过渡、动画：transform | transition | animation

9.[强制] 属性选择器或者属性值用双引号括起来。

10.[强制] 为了保证一致性和可扩展性，每个声明应该用分号结束。

11.[强制] 为了易读性和便于快速编辑，统一将语句分为多行。

12.[建议] 对于 sass 或 less 中选择器的嵌套，避免嵌套没有任何内容的选择器，并且遵循以下嵌套顺序：

• 当前选择器的 @extend 和 @include
• 当前选择器的样式属性
• 父级选择器的伪类选择器（:hover，:active，:first-letter等）
• 伪类元素（:before 和 :after）
• 父级选择器的声明样式（.selected，.active 等）
• 上下文媒体查询
• 子选择器作为最后的部分

JS 相关

1.[强制] 代码写注释，代码写注释，代码写注释！

2.[强制] 变量和函数命名使用小驼峰式命名；文件名称使用大驼峰式命名。

3.[强制] 命名必须表明该文件、函数、变量的用意。

4.[强制] 使用 let 或者 const 代替 var。

5.[强制] 禁止修改被定义为 const 类型的变量。

6.[建议] 使用字符串模板替换字符串拼接。

7.[强制] if,else 禁止简写。 

8.[建议] 变量赋值、if else、循环遍历、操作符等前后加空格，方便阅读。

9.[建议] 函数不能超过100行，超过应考虑拆分。

10.[强制] 禁止重复引用。

11.[建议] 使用 import 、export 代替 require、module.exports。

12.[强制] 使用 === 代替 ==。

13.[强制] 单行注释以双斜线 // 开始，双斜线与注释内容之间保留一个空格。

14.[强制] 多行注释按照 /* 注释说明 */书写。

15.[强制] 禁止使用 eval()语句，因为它存在安全隐患，导致脚本注入攻击。

16.[建议] 能用 css 实现的不用 js 实现。

17.[建议] 减少 js 操作 DOM。