合理的规范,能在多人开发的时候,起到意想不到的效果。
0. 前文
文章内容包括但不限于:本地开发环境、代码格式化、Vue 风格指南、Git 提交基本规范指南、新人上手指南、注释...
文章目标:社区主流 + 适合中小公司
1. 本地开发环境
IDE
默认情况下,我们采用 Visual Studio Code 编辑器编写前端代码。如果你是开发 Vue2 项目,那么你最少需要在 VSCode 中安装并开启这些插件:
- Vetur:Vue2 官方插件
- Eslint:代码校验
- Prettier:代码格式化
当然 Eslint 和 Prettier 这两个插件最好是配合项目中的对应依赖进行使用,假如你的项目没有这两个依赖(那建议你学会配置,或者至少找一个配置好这两个依赖的模板项目进行开发,例如:V3 Admin Vite)。
对于配置好的项目来说,你在 Ctrl + S 保存代码的时候,Eslint 与 Prettier 可能就已经开始工作了,将你的代码自动进行格式化。
假如你的项目是一个没有配置好的项目,那么至少建议你右键鼠标,选择 Prettier 插件进行格式化。
假如你的项目只配置了其中一个插件,例如只配置了 Eslint,那么建议你只开启你的 Eslint 插件,并且在保存代码时,选择采用 Eslint 来进行格式化(是的,Eslint 也具备一部分格式化能力)。
如果你是 Vue3 项目,那么你最少需要安装并开启这些插件:
- Volar:Vue3 官方插件(注意不要和 Vetur 同时开启,避免插件冲突)
- Eslint:代码校验
- Prettier:代码格式化
Node
Node 版本是要根据具体项目来安装的,但是当前时间的话(2023年10月31日),一般安装 16+ 版本的就可以通用了
2. 代码格式化
- Tab 键一般情况下设置为两个空格或四个空格大小
- 项目有配置 Prettier 时,一般采用 Prettier 插件格式化
- 项目没有配置 Prettier 时,但配置了 Eslint 时,一般采用 Eslint 插件格式化
- 项目 Prettier 和 Eslint 都没有配置时,一般采用 Prettier 插件进行格式化
3. Vue 风格指南
必要的(必须严格执行)
Prop 的定义应该尽量详细
在你提交的代码中,prop 的定义应该尽量详细,至少需要指定其类型。
为 v-for 设置 key
在组件上总是必须用 key 配合 v-for,以便维护内部组件及其子树的状态。
v-for 时将 index 当做 key
在对 v-for 循环出来的列表有删除操作的时候,切记不要轻易使用 index 当做 key!可以像上图中那样,用唯一的 id 当做 key。
至于为什么,请仔细阅读这篇文章:Vue2.0 v-for 中 :key 到底有什么用? - 知乎
避免 v-if 和 v-for 用在一起
一般在两种常见的情况下会倾向于这样做:
- 为了过滤一个列表中的项目 (比如 v-for="user in users" v-if="user.isActive")。在这种情形下,请将 users 替换为一个计算属性 (比如 activeUsers),让其返回过滤后的列表。
- 为了避免渲染本应该被隐藏的列表 (比如 v-for="user in users" v-if="shouldShowUsers")。这种情形下,请将 v-if 移动至容器元素上 (比如 ul、ol)。
推荐的(公司内严格执行)
单文件组件文件名的大小写
单文件组件文件名应该要么始终是单词大写开头 (PascalCase),要么始终是横线连接 (kebab-case)。
这里社区里一般默认采用大写开头的驼峰式命名。
Prop 名大小写
在声明 prop 的时候,其命名应该始终使用 camelCase,而在模板和 JSX 中应该始终使用 kebab-case。
4. Git 提交基本规范指南
commit 规范
前端这边默认采用前端开源社区主流的 commit 规范:
reference vue specification (Angular)
- feat: Add new features
- fix: Fix the problem/BUG
- style: The code style is related and does not affect the running result
- perf: Optimization/performance improvement
- refactor: Refactor
- revert: Undo edit
- test: Test related
- docs: Documentation/notes
- chore: Dependency update/scaffolding configuration modification etc.
- workflow: Workflow improvements
- ci: Continuous integration
- types: Type definition file changes
- wip: In development
简单翻译翻译就是:
- feat: 增加新的业务功能
- fix: 修复业务问题/BUG
- perf: 优化性能
- style: 更改代码风格, 不影响运行结果
- refactor: 重构代码
- revert: 撤销更改
- test: 测试相关, 不涉及业务代码的更改
- docs: 文档和注释相关
- chore: 更新依赖/修改脚手架配置等琐事
- workflow: 工作流改进
- ci: 持续集成相关
- types: 类型定义文件更改
- wip: 开发中
实际操作中,就会呈现下图这样统一规范且语义化的 commit 记录:
当然,这里的话只是规范你的描述信息。至于何时提交一个 commit 的话,我们简单采用一个原则:完成一件事情,就提交一次 commit。而不是等到你写完一整天的代码后,才在下班前只提交一次。
代码冲突
- 多人合作开发项目是,经常会遇到代码冲突的情况。这种时候不要惊慌,如果你不熟悉解决冲突的流程,那么你应该在发生冲突时,尽快备份你的本地代码备用。
- 我们提交代码的基本规则是:先 pull,再 push,并始终保持本地代码和远程代码同步。 这能大大降低冲突的概率!简单解释一下为什么:代码冲突是指我们和别人同时修改了一处相同的代码。git 这时候不知道并该采用谁的代码,就会抛出冲突,让程序员自己解决冲突(就是让你从你和你同事的代码里选择一份)。如果你始终遵循先 pull 再 push 的原则,那么在你刚到公司,你应该自觉 pull 同步一下代码,写代码前也要 pull,提交代码前也要 pull,最后才是 push。这能尽可能的保证你是在最新的代码版本上进行编写新的代码,而不是在老版本的代码进行编写新代码,可以有效的避免你去修改了别人的老代码(实际上你的同事早就更新了这段代码),从而导致冲突。
- 如果你必须要去修改同事的代码,或者要去修改公共模块的代码。你其实可以给你的同事打个招呼,问问他本地有没有要推送的代码。可以让他先推送后,你在去基于最新的代码修改。修改完成后,也可以提醒一下你的同事 pull 一下你的刚才提交的代码。
- 如果你是第一次遇见代码冲突,不要紧张 。你可以自行上网搜索试着解决它,或者第一时间找一个同事来指导你。假如代码比较重要,切记备份代码,并且不要使用强制推送去污染远程的代码。
5. 新人上手指南
确保熟悉以下几点后,就可以尝试上手一些真实的项目开发了:
-
熟悉常用 Git 命令(clone/add/commit/pull/push),然后熟悉 Git 可视化软件,比如 Sourcetree
-
理解 Git 中 "始终先 pull 再 push" 的规范,防止多人合作时提交代码冲突
-
熟悉一个开源的后台管理模板,比如 v3-admin-vite(vue3) 或 vue-admin-template(vue2)或 若依(vue2)
-
重点熟悉项目的登录、鉴权、权限三个模块。也顺便去看看它对表格的 CRUD
-
学会配置本地开发环境(vscode、node 16+、pnpm 8+、yarn 1.22.x、eslint 插件、prettier 插件、vue3 的话是两款 volar 插件、vue2 的话是 vetur 插件 )
-
vscode 配置为保存代码时,自动 eslint 校验代码
-
注意有些项目是用的 yarn,有些是 pnpm,甚至有些是 npm(可以通过 lock 文件来识别、或者看该项目文档有没有提示),根据具体的项目选择不同的工具,不能在同一个项目中混用(出问题了后可以删除 node_models、甚至删除 lock 文件,然后重新依赖)
-
不能用 npm 命令来安装 yarn,要去 yarn 官网下载安装包
6. 注释
- 基本的注释:至少得告诉别人,该函数或者该变量是做什么用的。
- 优秀的注释:好的代码注释是用来告诉别人你为什么写这样的代码,而不是告诉别人你的代码做了什么
- 优秀的命名:如果你的变量命名风格统一且友好,那么你其实就不用写太多基本的注释 ,因为别人看见变量名就知道你要做什么。这时候,你可以大胆的去写优秀的注释。