不完全前端规范指南

合理的规范,能在多人开发的时候,起到意想不到的效果。

0. 前文

文章内容包括但不限于:本地开发环境、代码格式化、Vue 风格指南、Git 提交基本规范指南、新人上手指南、注释...

文章目标:社区主流 + 适合中小公司

1. 本地开发环境

IDE

默认情况下,我们采用 Visual Studio Code 编辑器编写前端代码。如果你是开发 Vue2 项目,那么你最少需要在 VSCode 中安装并开启这些插件:

  1. Vetur:Vue2 官方插件
  2. Eslint:代码校验
  3. Prettier:代码格式化

当然 Eslint 和 Prettier 这两个插件最好是配合项目中的对应依赖进行使用,假如你的项目没有这两个依赖(那建议你学会配置,或者至少找一个配置好这两个依赖的模板项目进行开发,例如:V3 Admin Vite)。

对于配置好的项目来说,你在 Ctrl + S 保存代码的时候,Eslint 与 Prettier 可能就已经开始工作了,将你的代码自动进行格式化。

假如你的项目是一个没有配置好的项目,那么至少建议你右键鼠标,选择 Prettier 插件进行格式化。

假如你的项目只配置了其中一个插件,例如只配置了 Eslint,那么建议你只开启你的 Eslint 插件,并且在保存代码时,选择采用 Eslint 来进行格式化(是的,Eslint 也具备一部分格式化能力)。

如果你是 Vue3 项目,那么你最少需要安装并开启这些插件:

  1. Volar:Vue3 官方插件(注意不要和 Vetur 同时开启,避免插件冲突)
  2. Eslint:代码校验
  3. Prettier:代码格式化

Node

Node 版本是要根据具体项目来安装的,但是当前时间的话(2023年10月31日),一般安装 16+ 版本的就可以通用了

2. 代码格式化

  1. Tab 键一般情况下设置为两个空格或四个空格大小
  2. 项目有配置 Prettier 时,一般采用 Prettier 插件格式化
  3. 项目没有配置 Prettier 时,但配置了 Eslint 时,一般采用 Eslint 插件格式化
  4. 项目 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。而不是等到你写完一整天的代码后,才在下班前只提交一次。

代码冲突

  1. 多人合作开发项目是,经常会遇到代码冲突的情况。这种时候不要惊慌,如果你不熟悉解决冲突的流程,那么你应该在发生冲突时,尽快备份你的本地代码备用
  2. 我们提交代码的基本规则是:先 pull,再 push,并始终保持本地代码和远程代码同步。 这能大大降低冲突的概率!简单解释一下为什么:代码冲突是指我们和别人同时修改了一处相同的代码。git 这时候不知道并该采用谁的代码,就会抛出冲突,让程序员自己解决冲突(就是让你从你和你同事的代码里选择一份)。如果你始终遵循先 pull 再 push 的原则,那么在你刚到公司,你应该自觉 pull 同步一下代码,写代码前也要 pull,提交代码前也要 pull,最后才是 push。这能尽可能的保证你是在最新的代码版本上进行编写新的代码,而不是在老版本的代码进行编写新代码,可以有效的避免你去修改了别人的老代码(实际上你的同事早就更新了这段代码),从而导致冲突。
  3. 如果你必须要去修改同事的代码,或者要去修改公共模块的代码。你其实可以给你的同事打个招呼,问问他本地有没有要推送的代码。可以让他先推送后,你在去基于最新的代码修改。修改完成后,也可以提醒一下你的同事 pull 一下你的刚才提交的代码。
  4. 如果你是第一次遇见代码冲突,不要紧张 。你可以自行上网搜索试着解决它,或者第一时间找一个同事来指导你。假如代码比较重要,切记备份代码,并且不要使用强制推送去污染远程的代码。

5. 新人上手指南

确保熟悉以下几点后,就可以尝试上手一些真实的项目开发了:

  1. 熟悉常用 Git 命令(clone/add/commit/pull/push),然后熟悉 Git 可视化软件,比如 Sourcetree

  2. 理解 Git 中 "始终先 pull 再 push" 的规范,防止多人合作时提交代码冲突

  3. 熟悉一个开源的后台管理模板,比如 v3-admin-vite(vue3) 或 vue-admin-template(vue2)或 若依(vue2)

  4. 重点熟悉项目的登录、鉴权、权限三个模块。也顺便去看看它对表格的 CRUD

  5. 学会配置本地开发环境(vscode、node 16+、pnpm 8+、yarn 1.22.x、eslint 插件、prettier 插件、vue3 的话是两款 volar 插件、vue2 的话是 vetur 插件 )

  6. vscode 配置为保存代码时,自动 eslint 校验代码

  7. 注意有些项目是用的 yarn,有些是 pnpm,甚至有些是 npm(可以通过 lock 文件来识别、或者看该项目文档有没有提示),根据具体的项目选择不同的工具,不能在同一个项目中混用(出问题了后可以删除 node_models、甚至删除 lock 文件,然后重新依赖)

  8. 不能用 npm 命令来安装 yarn,要去 yarn 官网下载安装包

6. 注释

  • 基本的注释:至少得告诉别人,该函数或者该变量是做什么用的。
  • 优秀的注释:好的代码注释是用来告诉别人你为什么写这样的代码,而不是告诉别人你的代码做了什么
  • 优秀的命名:如果你的变量命名风格统一且友好,那么你其实就不用写太多基本的注释 ,因为别人看见变量名就知道你要做什么。这时候,你可以大胆的去写优秀的注释。

7. 单元测试

单元测试框架 Vitest 上手指南

相关推荐
逐·風15 分钟前
unity关于自定义渲染、内存管理、性能调优、复杂物理模拟、并行计算以及插件开发
前端·unity·c#
Devil枫44 分钟前
Vue 3 单元测试与E2E测试
前端·vue.js·单元测试
尚梦1 小时前
uni-app 封装刘海状态栏(适用小程序, h5, 头条小程序)
前端·小程序·uni-app
GIS程序媛—椰子2 小时前
【Vue 全家桶】6、vue-router 路由(更新中)
前端·vue.js
前端青山2 小时前
Node.js-增强 API 安全性和性能优化
开发语言·前端·javascript·性能优化·前端框架·node.js
毕业设计制作和分享3 小时前
ssm《数据库系统原理》课程平台的设计与实现+vue
前端·数据库·vue.js·oracle·mybatis
程序媛小果3 小时前
基于java+SpringBoot+Vue的旅游管理系统设计与实现
java·vue.js·spring boot
从兄3 小时前
vue 使用docx-preview 预览替换文档内的特定变量
javascript·vue.js·ecmascript
凉辰4 小时前
设计模式 策略模式 场景Vue (技术提升)
vue.js·设计模式·策略模式
清灵xmf4 小时前
在 Vue 中实现与优化轮询技术
前端·javascript·vue·轮询