从实际项目谈开发规范，你中招了吗？

• 「本文已参与好文召集令活动，点击查看：后端、大前端双赛道投稿，2万元奖池等你挑战！」

前言

• 最新更新一篇 前端开发基本规范，点击查看。
• 最近接手了一个其他项目组手上的项目，具体是几手项目我也不好说，通过查看 git 的提交历史，这至少是转过 2 个项目组的项目，这里面的问题不可畏之不多，下面我细细道来并赋之问题应该怎么解决及优化。

命名规范

• 我主要说一些日常开发中在任何团队作为一个前端程序员至少应该做到的规范。

1. 文件命名

• 针对一个项目，对于组件、文件、文件夹的命名每一类都应该有统一的命名，统一使用小驼峰/大驼峰/小写+英文横线分隔符。 在这个项目中，这三种居然同时存在！！！

2. 函数命名

• 对于函数命名应该统一为小驼峰，当然也可以使用大驼峰，但建议使用小驼峰。
• 这个函数从字面知道是过滤，那过滤什么呢？不知道，也没用注释。函数名应清晰表达出函数的功能，我们可以使用 get 、set 、 hide 、 show 等动词开头，接上函数具体做的事情。不要出现中文、拼音等！！！

3. JavaScript 变量命名

• 在这个截图中，我们可以看到 isEdit 、loading 、 type 等字段，但通过变量的名称我们并不知道这是哪个的编辑、加载以及类型。我们需要在变量中加入区分的部分，例如 isDepartmentEdit 、 departmentInfoSaveLoading 、 departmentType 等。

4. CSS 命名

• 现在的项目开发中，基本上会用到 LESS 、 SASS 等预编译语言，所以我们在 CSS 命名时，可以使用相应的特性，每个组件最外层有一个特定的组件名 class，后面每嵌套一层在后面加对应的功能名/方向等，不要无意义简写单词。
  • 优势：清晰的层级、样式通过 & 符号嵌套很方便、不易产生样式冲突等。
  • 劣势：层级过深 class 名特别长（可以省略前几级，省略后可能产生样式冲突，可以使用 scope 等解决）、会增加文件体积。

JavaScript

1. 公共方法

• 对数据的判空/无效值，我们可以使用一个通用的方法来实现，使用时引入即可，而不是每个地方都写一次判空逻辑。其他方法类似，有 2 处及以上的地方用到时（代码多、逻辑复杂），建议抽取公共方法。
  • 优点：方便、减小代码体积。

2. 严格相等、不等符号等

• 还是上一张图片，我们应该在项目中都使用严格的相等、不相等符号。
  • 优点：避免类型转换出现意料之外的逻辑错误。

3. 空语句

• 截图中有 if 判断，但是没有操作，else 中才有。在逻辑判断中，有对应需要的操作再写对应的语句块，没有就省略。不要出现空语句块！！！
  • 优点：美观、逻辑清晰、减小代码体积。

4. 多处使用的相同数据结构

• 在组件内多处使用的相同数据结构，我们可以使用 const 在组件内（VUE中）<script> 的开头声明一个变量来存储。全局不同文件的可以写在 common 文件下的 constant.js 文件中，使用时引入该变量。
  • 优点：美观、减小代码体积。

5. 冗余操作

• 在使用数据时，数据即不是定义好的变量，而是只有当前才会用的，所以上面的图片不需要 reverse ，我们只需要写的时候反过来即可。
  • 优点：可以提升代码执行速度（少的话看不出来）。

6. 类似方法合并

• 上面图片中有多个 getXxxxStatistic 方法，我看了里面的逻辑，有几个不同点：
  1. 请求地址不同
  2. 传入的数据来源（变量）不同（结构相同）
  3. 存储请求结果的变量不同
• 相信大家都看出来了，对于这些不同点，其实完全是可以抽成一个公共方法的，我们只需要通过传递不同参数就可以达到相同的效果了。
  • 优点：减小代码体积。
  • 缺点：会增加代码逻辑，但一般不会太复杂，如果写成公共方法逻辑会很复杂，建议多考虑一下实际情况。

7. 判断优雅

• 之前我写了一篇关于判读等逻辑处理的优雅写法的文章，有兴趣的可以看看，传送门 JavaScript 判断优雅写法
• 这里的 if ... else 完全可以声明一个对象来处理，而且这个判断还多处使用了。这样的话，声明一个变量可以大大减少代码量。
• 通过观察 url 地址，我们发现其实就只有中间部分不同，并且不同的部分和 corpusType 的值一样，所以我们还可以这样写。

const url = `/api/${this.corpusType}/update`;

8. 循环请求

• 这个设计一开始我也不明白为什么要做循环请求，当选中的数据过多时，这发出的请求会有多少，每次都会弹出成功提示。这直接提交一个数组数据不就行了吗？直到我看到请求的封装才知道。
• post 请求居然发送的是字符串？我直接裂开了，并且最后多余的 & 符号也没处理，相对而言这都是小问题。
  • 不要循环请求，也不要使用 post 去发送字符串。

代码注释

• 注释的作用：给自己看，方便回忆；给同事看，协同工作。 当一个项目任你代码写的再漂亮、命名再怎么规范、逻辑再怎么清晰，时间长了以后，你再回过头来看，肯定还是会有看不明白的地方，你就会花费时间去梳理，如果有注释，你就可以短时间找到他的作用。
• 这个项目中只有少许的注释，可能 1% 都不到。有很多文件，全文件没有一个注释。

1. HTML 注释

• 很多人肯定会问，HTML 还需要写注释吗？我想说的是，这也是需要的，例如：我们有一个页面，它有 2 个甚至以上的变量去控制它不同状态下显示不同内容。方法一：通过一个方法将多个变量转移到参数中，在把注释写到方法中；方法二：在不同页面的位置增加对应变量的值注释。

2. JavaScript 注释

• JavaScript 注释主要有方法注释，复杂逻辑注释。

1. 方法注释

   • 上面截图中的方法，梳理这个方法都用了快一天时间。仅有的注释也是我增加功能时添加的，不要说为什么你梳理后不把注释加上呢？原因就是，我只把我想要的内容拿到，其他的没管！
   • 自动添加注释使用 VS Code 的可以使用koroFileHeader插件，下面是我之前写的做一个示例：

2. 复杂、特殊逻辑

HTML、CSS

1. 额外标签

• 每个表情都应该有开始和对应的结束标签成对出现或者自闭合（例如：input、img 标签等）。

2. 空标签

• 不要出现无意义的空标签，即使清除浮动，现在有 flex、grid 布局，基本上 float 都不需要使用。

3. 标签嵌套混乱

• 不要使用行类标签嵌套块级标签，也不要使用类似 p 标签去嵌套 div 标签，如果对标签不了解建议仅使用 div及 span 标签。

4. 少写内联样式

• 在标签上既然有 class ，又单独使用 style 设置一个样式，但样式又不受变量影响的，应避免。

5. 合并公共样式

• 上图中，10 多个标签的样式除了宽度不一样其他都是相同的，所以我们把样式写在一个 class 里面，不同的宽度再额外增加一个带宽度标识的 class 即可。
  • 优点：减小代码体积，增加代码可读性。

其他

1. 组件

• 相同的功能，有公共组件的应该统一使用公共组件，保持使用方式的一致性。（由于物质原因无法上传截图，把相关的代码贴在下面，以分页组件示例）。

• 还有其他文件，有些使用二次封装组建、有些使用的 element 的组件。

2. 代码缩进

• 不管是 JavaScript 还是 HTML 亦或者是 CSS 我们都应该保持严格的缩进对齐，使得代码逻辑清晰，可以快速找到对应的模块区域。

感悟

• 接手时间不长，肯定还有些问题没有看到，遇到了再补充。
• 都说程序员最讨厌的四件事：写注释、写文档、别人不写注释、别人不写文档。 但为了和谐，该有的注释、文档还是应该有（有歧义、参数过多、逻辑复杂等情况）。
• 写代码这件事不是一件简单的事，不只是要完成对应的功能，还要想怎么把代码写好。怎么算写好呢，一个从未接触过这个项目的人，拿到代码也能清楚或花少量时间知道在做什么。

往期精彩

• 从0搭建Vite + Vue3 + Element-Plus + Vue-Router + ESLint + husky + lint-staged
• 「前端进阶」JavaScript手写方法/使用技巧自查
• JavaScript设计模式之简介及创建型模式
• 公众号打开小程序最佳解决方案（Vue）
• Axios你可能不知道使用方式

「点赞、收藏和评论」

❤️关注+点赞+收藏+评论+转发❤️，创作不易，鼓励笔者创作更好的文章，谢谢🙏大家。