目前遇到的问题
作为一名前端工程师，陆陆续续负责了不少项目，这些项目中，有一些是正在迭代的，其他同事同时在负责的项目，但是也有不少项目，要么就是老旧项目维护的同事已经离职或转岗了的，要么就是新项目从 0 开始的，再加上前端代码积累速度和迭代速度都比较快，其中暴露了不少问题。
我身边的大多数程序员都有一个特点，就是喜欢把具体的东西抽象化，我们通常会抽象出公共的函数或方法、公共的类或HOC，放在一起，集中在项目的某一个文件夹下，叫做 js 文件夹或 lib 文件夹（以下我们用 js 文件夹代表公共函数文件夹 ）。
这样做的确带来了很多便利，但同时也有一些隐患：
- js 文件夹下代码越来越多，而且大多数鹅厂小伙伴的作风是 0 文档 0 注释，这给新接手项目的同学熟悉项目带来了极大的麻烦。
- 不同项目都有自己的 js 文件夹，在开发一个新项目时，我们通常的做法是：
- 直接将原有项目的 js 文件夹拷贝到新项目中，这样在新项目中，我们也可以直接使用这些公共函数了。
- 将原有项目的部分 js 文件拷贝到新项目中，并且随着新项目的开发，增量拷贝。
- 以上两种做法，本质区别不大，前者会直接给新项目增加很多无用代码（原有项目中所谓的公共函数在新项目中并不一定会用到），而对这两种方式，如果我们要修复一个 bug，修改或升级公共代码中的一个文件，那么我们就要一个一个的，将修复好的文件拷贝到不同的项目中，如果项目多了并且已经交由不同的人维护了，这简直是一个灾难。
- 由于公共 js 文件夹下内容比较多，并且有的开发同学习惯以 ‘urlUtils.js’、’strUtils.js’ 这种方式来整合一些小的函数集，这样会造成函数重复的隐患（毕竟我们一个文件一行行的去分析目前的公共库已经有了哪些能力是不现实的），我观察过之前自己接手的一个不算复杂的项目（潘多拉），其仅仅是从 url 解析 query 这种功能函数，就有多达 3个(甚至更多)，分布在 js 文件夹以及 node_modules 里面，这显然是不同的维护人员由于信息不对称重复引入的。
- 对于怎么样才能算作“公共”函数，目前是缺乏一个 review 过程的，任何项目开发人员，几乎都可以无限制地在公共 js 文件夹下增加内容，并在之后被携带着拷贝到其他项目中，这其中有些函数，也许并不适合在这里。
问题归纳与解决
实际上，总结下来，我们需要解决三个痛点：
- 以低成本的方式增加高可读性的文档，方便新接手项目的同学熟悉。
- 解决跨项目之间的公共函数复用和更新维护困难的问题。
- 增加必要的 review 环节，对公共函数库的必要性和代码正确性进行 review。
就第一个问题而言，其实现在的前端文档工具链已经极大降低了写文档的成本了，利用 jsdoc 或 esdoc 等文档生成工具，我们基本上已经不需要手动写文档，而是在写代码的同时写注释，就可以自动生成文档，并且配合相关的编辑器插件，一部分注释都可以自动生成。
但是目前我经历的大多数项目还是没有文档，这里可能是由于以下四个原因：
- 部分同学并不知道有 esdoc、jsdoc 这种比较好用的文档生成工具。
- 开发组中没有人去推动，文档不属于 KPI 和考核的内容，加之时间紧迭代快，缺乏前人栽树的动力。
- 虽然现在的文档生成工具比较简单了，但一般还是需要一定的配置，也有一点上手成本。
- 生成的文档不能十分满足需求，例如 esdoc 默认只能生成 html 格式的文档，在编辑器里面没法直接看。
针对第一个问题，qlc 做出了一些努力：
- 0 配置，全自动化生成文档，甚至集成到了其他开发流程中，命令行也不用敲。
- 基于 esdoc 以及开源插件二次开发，可以选择性生成 html 和 markdown 格式的文档，注重文档体验。
- 基于 esdoc 注释写作成本更低，更能节省时间。
跟 jsdoc 相比，esdoc 使用方式比较简单，不需要严格使用标签，而且能够支持搜索，并且官方资料更为齐全。
至此，使用 qlc 生成文档，已经非常简单了。
第二、第三个问题实际上是公共函数库的维护问题，qlc 也设计了对应的流程，着力解决该问题：
- 首先有一个远程公共库（基于 git）。
- 对于某一个项目而言，可以从远程库中下拉所需要的公共函数/类，并自动生成文档。
- 如果我们对某一个项目增加了一个公共函数并且认为可以为更多的项目所用，命令行上传到远程库自动触发 MR，维护人员 review 通过后即可供其他项目使用。
- 修复或更新某一个公共函数之后，我们只需同步到远程库，其他项目维护人员在命令行工具的辅助下同步即可。
更多
到此，你是否认为 qlc 给你带来了一定的价值呢，可以到 qlc 的官方仓库查看更多的文档细节
