• 浅谈前端开发规范

    一个好的程序员肯定是要能书写可维护的代码,而不是一次性的代码,怎么能让团队当中的其他人,甚至过一段时间之后的你,再看自己某个时期写的代码,依然能看懂?这就涉及到规范你的代码了。

     

    一、规范代码的好处

    1、从根本上降低开发成本:

    提高代码整体的可读性、可维护性、可复用性。

    2、保证代码的一致性:

    软件系统中最重要的因素之一就是编码的一致性。如果编码风格一致,也更加易于维护,因为团队内任何人都可以快速理解并修改。

    3、提升团队整体效率:

    开发人员通常需要花费大量的时间来解决代码质量问题,如果都按照规范编写,也有助于团队尽早发现问题,这将提高整个交付过程的效率。

    二、不规范代码的弊端

    1、增加团队成员间的协作负担:

    由于缺乏规范,导致代码风格不一,极端情况下,某段代码只有某个人能修改。

    2、团队间协作更加困难:

    由于开发人员要适应不同的风格,会导致效率低下。

    3、回顾困难:

    在review期间,可能经常为类似的事情做过多的讨论。

    4、影响降低团队整体效率:

    影响团队的生产力和质量,严重的甚至会影响团队和谐。

    三、为什么很多团队缺乏规范

    1、当开发人员被要求在短时间内完成任务时,通常会回避质量标准。

    2、长时间养成的开发习惯很难在短时间内去改变。

    3、有的时候虽然达成了一致,但在开发中依旧我行我素。

    四、规范包含哪些内容

    我们平时理解的前端开发规范,更多层面的是编码层面的规范,实际上远不止这一个。比如技术栈规范、浏览器兼容规范、项目文件结构规范、UI设计规范、前后端协作规范等,以下主要从这六个方面简单介绍下前端开发规范。

    1、技术栈规范

    前端目前主要有三大框架Vue、React和AngularJS。每一个框架背后都是一个架构、一个生态。每个框架背后牵涉着开发思维、生态系统、配套工具、最佳实践、性能调优。要精通和熟练一个框架需要付出的成本是很高。

    所以说团队的开发效率是基于稳定且熟练的技术栈的。稳定的技术栈规范有利于团队协作和沟通; 另外如果团队精通这个技术栈,当出现问题或者需要深入调优, 会相对轻松。

    前端技术栈规范主要包含下面这些类型:

    ① 编程语言 – Typescript或Javascript

    ② UI框架及其配套生态(路由、状态管理、组件库、国际化、动画、服务端渲染、脚手架、CLI工具、组件测试等)

    ③ 样式。命名规范、预处理器等

    ④ 动画引擎

    ⑤ 项目构建工具流。webpack、vue-cli

    ⑥ 包管理器。npm、yarn

    ⑦ 开发工具、工具库(moment.js)、版本管理(gitlab)等

    2、浏览器兼容规范

    前端团队应该根据应用所面对的用户情况、应用类型、开发成本、浏览器市场统计数据等因素,来制定自己的浏览器兼容规范。不过确定哪种兼容策略,应该取决于用户比重,如果大部分用户使用的是现代浏览器,就应该使用优雅降级,为现代浏览器提供最好的体验,而旧浏览器则退而求之次,保证大概的功能,反之选择渐进增强,保证低版本浏览器的体验,对于支持新特性的新浏览器提供稍好的体验。

    有了浏览器兼容规范,前端开发和兼容性测试就有理有据,避免争议; 同时它也是前端团队的一种对外声明,除非特殊要求,不符合浏览器兼容规范的浏览器,前端开发人员可以选择忽略。

    我们也可以根据浏览器市场分布情况、用户占比、开发成本等因素对将浏览器划分为多个等级,不同等级表示不同的支持程度:

    ① 完全兼容: 保证百分百功能正常

    ② 部分兼容: 只能保证功能、样式与需求大致一致。对于一些不影响主体需求和功能的bug,会做降低优先级处理或者不处理

    ③ 不兼容: 不考虑兼容性

    3、项目文件结构规范

    主要包含项目的命名、项目的文件结构、版本号规范等。

    下面简单列举一类项目文件结构:

    ① README.md: 项目说明。你可以在这里提供关于项目的关键信息或者相关信息的入口。一般包含下列信息:

    · 简要描述、项目主要特性;

    · 运行环境/依赖、安装和构建、测试指南;

    · 简单示例代码;

    · 文档或文档入口, 其他版本或相关资源入口;

    · 联系方式、讨论群;

    · 许可、贡献/开发指南。

    ② CHANGELOG.md: 放置每个版本的变动内容, 通常要描述每个版本变更的内容。方便使用者确定应该使用哪个版本。

    ③ package.json: 前端项目必须. 描述当前的版本、可用的命令、包名、依赖、环境约束、项目配置等信息。

    ④ .gitignore: 忽略不必要的文件,避免将自动生成的文件提交到版本库。

    ⑤ docs/: 项目的细化文档, 可选。

    ⑥ examples/: 项目的示例代码,可选。

    ⑦ build: 项目工具类脚本放置在这里,非必须。如果使用统一构建工具,则没有这个目录。

    ⑧ dist/: 项目构建结果输出目录。

    ⑨ src/: 源代码目录。

       – src 开发目录

    – pages 视图

    – module-a 模块A

    – components 私有组件

    – ComA.tsx

    – ComB.tsx

    – index.module.less

    – index.tsx

    – Content.tsx

    – module-b 模块B

    – components 公共组件

    – index.ts 导出所有组件

    – header

    – index.tsx

    – index.module.less

    – User.tsx

    – useGetBaseInfo.hooks.ts

    – routers 路由文件

    – store redux中的数据

    – utils 这里是以utils为后缀

    – index.ts

    – a.utils.ts

    – b.utils.ts

    – hooks 这里是以hooks为后缀

    – index.ts

    – a.hooks.ts

    – b.hooks.ts

    – styles 静态资源文件

    – service api请求,这里是以api为后缀

    – a.api.ts 按照后端微服务进行划分

    – b.api.ts

    – constans 常量

    ⑩ tests/: 单元测试目录。

    ⑪ tests: 全局的测试目录,通常放应用的集成测试或E2E测试等。

    ⑫ .env*: 项目中我们通常会使用环境变量来影响应用在不同运行环境下的行为。可以通过dotEnv来从文件中读取环境变量. 通常有三个文件:

    · env 通用的环境变量;

    · env.development 开发环境的环境变量;

    · env.production 生成环境的环境变量。

    4、编码规范

    每一个程序员心目中对‘好代码’都有自己的主见,统一的编码规范可以避免不必要的论战和争议,有利于团队项目的长远维护。一致性的代码规范可以增强团队开发协作效率、提高代码质量、减轻系统维护的负担。

    以下主要从HTML、JS、CSS、代码格式化这四个方面谈谈编码规范:

    ① HTML规范

    使用 HTML5 的文档声明类型 :

    DOCTYPE标签是一种标准通用标记语言的文档类型声明,它的目的是要告诉标准通用标记语言解析器,它应该使用什么样的文档类型定义(DTD)来解析文档。

    使用文档声明类型的作用是为了防止开启浏览器的怪异模式。

    没有DOCTYPE文档类型声明会开启浏览器的怪异模式,浏览器会按照自己的解析方式渲染页面,在不同的浏览器下面会有不同的样式。

    如果你的页面添加了,那么就等同于开启了标准模式。浏览器会按照W3C标准解析渲染页面。

    详细规范可查看:https://codeguide.co/#html

    ② JS规范

    函数变量命名、代码注释等。JS/TS主流的大致有这几种:

    · Airbnb JavaScript Style Guide:

    https://github.com/airbnb/javascript
    · Google JavaScript Style Guide:https://google.github.io/styleguide/jsguide.html]

    · Idiomatic JavaScript Style Guide:

    https://github.com/rwaldron/idiomatic.js

    · JavaScript Standard Style Guide

    ③ CSS规范

    ID和class的命名、合理使用ID、css选择器中避免使用标签名、使用子选择器、尽量使用缩写属性等,详细可参考以下网站:

    · Airbnb CSS / Sass Styleguide:

    https://css-tricks.com/bem-101/

    · Code Guide:

    https://codeguide.co/#css

    ④ 代码格式化规范

    由于每个开发者的IDE不同,即使IDE相同也会因为每个人的配置不一样导致格式化的结果不一样。如何确保团队内开发人员采用统一的格式化配置呢?

    这里给推荐大家使用 prettier,它内置了一套格式化的规则。细可参考以下网站:https://prettier.io/

    5、UI设计规范

    UI 规范的最大好处就是能够提质提效:

    ① 在开发者的角度,与设计规范同步形成研发资产,避免重复造轮子;

    ② 在测试的角度,能够避免重复的无意义走查;

    ③ 在UI设计师的角度,减少设计成本,提高设计效率,可以快速承接新需求;

    ④ 在产品角度,提高产品迭代与优化效率,降低试错成本;

    ⑤ 在用户角度,解决用户体验一致性。

    如果团队不打算制定自己的UI设计规范,则推荐使用现成的开源组件库:Ant Design、Element UI、iView、WeUI等

     6、前后端协作规范

    前端往往不能脱离后端而存在,和后端协作的时间也是比较长的。

    一个常用的前后端协作流程:

    ① 需求分析。参与者一般有前后端、测试、以及产品。由产品主持,对需求进行讲解,接受开发和测试的反馈,确保大家对需求有一致的认知。

    ② 前后端开发讨论。讨论应用的一些开发设计,沟通技术点、难点、以及分工问题。

    ③ 设计接口文档。可以由前后端一起设计;或者由后端设计、前端确认是否符合要求。

    ④ 并行开发。前后端并行开发,在这个阶段,前端可以先实现静态页面; 或者根据接口文档对接口进行Mock, 来模拟对接后端接口。

    ⑤ 前后端进行接口联调。

    五、前端开发规范实例

    1、项目情况

    多人开发同一个项目的不同模块;由于开发前没有制定规范,导致每个人的代码都是一种单独的风格;当其他人去修改代码时需要熟悉不同风格的代码,浪费了大量时间在阅读代码上;而且由于没有全局的样式规范,导致每个人都有一套自己的样式,在后期如果想要做统一的界面风格时需要每个人都去修改样式代码,增加了大量工作量。

    2、制定规范

    根据项目的实际情况,由于项目已经开发到一定程度,已经选好了开发框架,所以可以从编码和UI设计等方面进行规范。

    由于项目是一个管理系统,所以对于前端UI来说可以统一页面结构;制定一个统一风格的模板,开发的时候可以直接使用模板代码去做适应性的修改;

    由于缺乏统一的样式标准,导致后期统一风格时会花费大量时间,所以进行统一的样式分离,抽离公共的CSS样式去引用,方便后期统一修改;

    由于一些变量和函数命名过于简单比如a、b、c等,规范多使用一些语义化的单词去命名,方便理解和阅读;

    由于项目开发中前后端是同一个人开发,导致有些可能是后端的工作放到了前端去处理。比如分页功能,虽然这个是前后端都可以做的,但是如果使用前端去分页,这样就要需要一次性返回全部数据,数据量大的时候接口可能会返回很慢,导致页面空白时间比较长,所以建议有些逻辑功能要根据实际情况去决定是前端还是后端处理。

    3、最终成果

    项目代码结构基本上有一个统一的风格;各模块页面也有了统一的风格;用户体验较好;也方便了开发和维护。

    总结:

    一个人走得更快,一群人可以走得更远。统一规范的最根本目的是为了保证团队成员的一致性,从而减少沟通成本,提高开发效率。学会热爱标准,但要确保它们不是一成不变的。如果制定的规范不适合您的团队,请确保可以适应和重写所需要的任何规则。它并不是要强制执行一种工作方式,而是为了帮助促进团队之间的互动。
    «
    »
以专业成就每一位客户,让企业IT只为效果和安全买单

以专业成就每一位客户,让企业IT只为效果和安全买单