背景

去年下半年，我在微信书架里加入了许多技术书籍，各种类别的都有，断断续续的读了一部分。

没有计划的阅读，收效甚微。

新年伊始，我准备尝试一下其他方式，比如阅读周。每月抽出1~2个非连续周，完整阅读一本书籍。

这个“玩法”虽然常见且板正，但是有效，已经坚持阅读六个月。

已读完书籍：《架构简洁之道》、《深入浅出的Node.js》、《你不知道的JavaScript（上卷）》、《你不知道的JavaScript（中卷）》、《你不知道的JavaScript（下卷）》、《数据结构与算法JavaScript描述》、《WebKit技术内幕》。

当前阅读周书籍：《前端架构：从入门到微前端》。

通过流程化提高代码质量

项目的文档化：README搭建指南

一份好的搭建指南，应该和我们在GitHub上看到的开源项目是相似的，具有如下特点：

• 支持运行的环境。
• 必要的依赖准备，以及如何搭建。
• 项目的安装指南。
• 线上的示例或最后的运行环境。
• 相关的文档链接。
• 相关人员的联系方式，讨论群。

在大部分项目里，这些必要的资源放在README中，能大大地提高开发人员的效率。

绘制架构图：减少沟通成本

对于架构复杂的项目而言，架构图是必不可少的。架构图能让一个团队中的新成员快速地了解现有系统的各个组成部分。对于复杂的系统，架构图一般展示的是各个子系统之间如何通信；对于简单的系统，架构图则可以是由项目的技术栈组成的。

在简单的前端项目里，架构图可能只表现不同框架之间的关系，以及不同层级的组件库之间的使用关系。即使不看架构图，我们也可以清晰地了解项目的架构。

对于复杂的前端项目来说，我们可能采用微前端的方式来设计应用架构。各个应用之间可能存在一定的关联性，以及底层的一些共用依赖等。在微应用化的前端方案里，架构图的作用更多是描述项目的构建过程。

绘制项目架构图有多种方式，既可以使用代码生成，也可以使用专业工具绘制。当然，也可以是某次会议上的讨论结果，然后将拍照记录到文档中。总之，我们需要为后来者建立一个有效的文档机制，以方便未来的开发者能够在需要的时候，找到原有的系统设计和现在架构之间的一些差异。

可编辑文档库：提升协作性

绘制完项目架构图后，我们就需要找到一个可编辑的文档中心。同样的，我们优先关注于其是否可以版本化、图形可视化，以及追踪历史修改。它可以是：

• 可以记录版本历史的维基（Wiki）软件。
• 专业的协作工具，比如Atlassian的Confluence。
• 基于Git+Markdown的代码管理工具。

它应该还能支持以下功能：实时多人编辑、内容索引、图形可视化、实时搜索、打标签、检查清单、导入导出等。

记录架构决策：轻量级架构决策记录

轻量级架构决策记录是一种轻量级的架构记录方式，通常使用像Markdown这样的轻量级文本格式语言，它们既方便于开发人员编写，又适合于版本软件管理。同时，它还能结合到项目的代码中。架构决策记录将按顺序和数字编号，并且不会被重复使用。这些记录包含了影响架构、非功能需求、依赖关系、接口或构建系统技术等内容。

可视化文档：注重代码的可读性

相比传统的文档方式，使用Web技术制作出来的文档更具表现力、更容易吸引用户。在现今的前端框架里，为了更好地吸引开发者，并方便开发者使用，项目的文档通常是一些可交互的文档。

看板工具：统一管理业务知识

看板，对于敏捷项目来说是一个必不可少的工具。除了有了解项目进度、分配资源、发现问题的作用，它更重要的功能是记录用户故事，即我们拥有一个实时可翻阅相关业务内容的文档。在阅读代码的过程中，我们可以查找出代码修改的业务原因。

作为一个开发人员，过去笔者并不觉得这样的工具有什么帮助，直至遇到了一个有历史的遗留系统。由于系统差不多有10年的历史，在修改每一段代码前，都要了解项目的上下文。而由于人员的更换，写代码的开发人员、相应的业务分析师大都已经联系不上了。即使能找到相应的开发人员，他也记不住相应的业务信息。每当这个时候，我们就只能寄希望于系统曾经记录过这些需求及其变更历史。

提交信息：每次代码提交文档化

在团队协作中，使用版本管理工具Git、SVN几乎都是这个行业的标准。当我们提交代码的时候，需要编写提交信息。

项目方式

提交信息的主要用途是，告诉这个项目的其他人，在这次代码提交中做了些什么。比如，在更新了React Native Elements的版本后，提交信息为：[T] upgrade react native elements。对应修改的是：package.json和yarn.lock中的文件。一般来说，建议小步提交，即按自己的Tasking步骤来提交，每一小步都有对应的提交信息。这样做的目的是，防止在一次修改中修改过多的文件，导致后期修改、维护、撤销等困难。

开源项目方式

与我们日常工作稍有不同的是：工作中的发布计划一般都是事先安排好的，不需要changelog。而开源应用、开源库需要有对应的CHANELOG文件，其包含或添加了什么功能、修改了什么，等等。这个文件如果由人力来维护则是一件麻烦的事——我们需要翻阅过去的提交历史，并整理出所有重要的修改。因此，在开源世界里，就采用标准化提交信息，来自动化生成CHANGELOG文件。

通过流程化提高代码质量

Web应用通常面临着上线和质量之间的博弈——只要不影响用户体验，小的bug往往对于项目来说是可以“容忍”的。这样就可以早些上线，实现用户价值。此外，Web开发还受其开发的影响：一个是类似于敏捷方式的迭代式开发，另一个则是可以多次上线。

Web开发与一些特殊领域及行业的软件开发不同，一个开发成本上亿的软件，可能只会运行、部署一次，不会有第二次机会，如原子弹的控制系统。还有一些类型的案例，就是智能汽车上的自动驾驶系统，稍有不慎就会车损人亡。Web应用虽然更新困难，可它们还是能远程更新的。而在这些系统上，它们就更追求质量，而不是开发速度。Web应用部署如果失败可以回滚，虽然会带来一定的财务上的损失，但是极少会带来生命危险。

因此在质量和速度方面，在Web开发上保持着一个微妙的平衡。

代码预处理

在代码提交之前，我们还可以进行一些常见的操作：

• 静态代码分析（Lint），用于进行静态代码分析，常见的如Lint4j、TSLint、ESLint。
• 运行测试，为了不影响持续集成，我们需要在代码提交之前进行测试。

现在的编辑器（使用相应插件）、IDE可以提高技术手段，在开发的过程中分析静态代码，并随时提高建议。如Intellij IDEA和WebStorm就会根据TSLint来提醒开发者注意关于TypeScript代码的一些规范问题。

这些分析工具主要进行代码分析，如《全栈应用开发：精益实践》一书中所说，一般会进行如下一系列的风格检测：

• 规范函数名及变量。
• 代码格式规范。
• 限制语言特性。
• 函数行数限制。
• 多重嵌套限制。
• 未使用代码。
• .......

手动检视代码

除了使用Lint+Git Hooks的方式来自动化检测代码问题，手动地去检视代码也是一个不错的检查代码的方式。这种方式可以带来一系列的好处：

• 提高新成员的编程水平。
• 保证代码规范得以实施。
• 每个人对项目的代业务都会很熟悉。
• 提供项目代码的质量。
• 帮助成员熟悉工具和快捷键的使用。

使用工具提升代码质量

代码扫描工具

随着技术的发展，已经有一些工具能直接扫描代码，并帮我们发现代码中的Bug，如Sonar就是这样的一个工具。这些代码扫描工具通常都能通过静态分析代码执行自动检视，并检测多种编程语言上的错误、代码坏味道和安全漏洞。它可以报告出各种常见的、显式的代码问题，如switch语句没有default。当然，这些语法问题通常可以用CheckStyle来解决。

代码扫描工具还能与大部分构建工具、持续集成工具、源码管理工具配合使用。在这个时候，我们只需要配合源码管理工具或者持续集成工具，在提交代码后，进行相应的代码扫描命令，再生成测试报告。

IDE快速重构

IDE重构，即借助于IDE来对代码进行重构，它通常是由快捷键来触发的。它将重构的主要工作交给IDE，而不是由开发人员通过修改代码来完成。多数时候，我们只需要按下快捷键，再输入一些必要的名称、参数，重构就完成了。因此，它是在我们每天的开发中不可或缺的一部分。可以随时随地进行，而不需要预留一个专用的重构时间。

在日常开发中，我们编写的一些代码坏味道，都可以直接由IDE的快捷键完成重构。

测试策略

测试策略是架构中重要的一环，它用于保证项目质量及代码质量。测试并不能直接地减少Bug，它可以间接地减少代码反复修改出现的Bug——每当我们修改代码的时候，就极有可能破坏系统原有的功能。

过去，在Web应用中有一个很经典的“测试金字塔”的概念。

金字塔中的四个层级如下：

• 单元测试。
• 组件测试。含快照测试（Snapshot）。
• 契约测试/接口测试。相当于服务测试。
• E2E测试。端对端测试、集成测试。

总结

本篇文章从搭建指南开始入手，介绍了在前端项目中的各种文档类型，以及通用的文档工具。最后，我们回到代码中，一步步地将代码从本地提交转到了测试环节。此外，还讨论了与代码质量相关的内容，以及如何采用合适的代码测试策略。

作者介绍
非职业「传道授业解惑」的开发者叶一一。
《趣学前端》、《CSS畅想》等系列作者。华夏美食、国漫、古风重度爱好者，刑侦、无限流小说初级玩家。
如果看完文章有所收获，欢迎点赞👍 | 收藏⭐️ | 留言📝。