不写注释不写文档的小伙伴先等下
待我挽个剑花给你看

前端团队项目开发中常见的问题：

有多少项目在起步时是宏大计划，随着时间的流逝，却最终都演变成了垃圾山。

1.组件层面

项目中，存在多个不同人开发的功能几乎相同的组件。

尤其是组件数量达到一定量级的大型项目，这个问题最为突出

项目开发中会将先页面从ui层面上拆分为多个颗粒度较小的组件，最后组装为一个页面。开发过移动端项目的同学感受会更深一些。相对来说pc端页面相对特异性较高，所以对于拆分组件的需求没有那么高。

当多个开发人员协同开发一个项目时，需求的划分不再以页面为区间，而是以组件模块为区间。相似度高、可复用的组件归类后分配任务。

在这个过程中会存在下面这种情况：
前端A、前端B同学需要开发的组件中有一部分是前端C同学曾开发好的，直接引用就可以。大多数这种沟通是依赖开发人员之间的口头沟通，这种不稳定的沟通就可能会造成前端A、前端B同学都又写一遍这个组件。

而且

有些项目进度长达两三年、三四年，且不说开发之间的配合程度，光是开发人员恐怕都能换几轮了。

当新接手的开发人员拿到项目代码，若是之前文档写的不够完善，那基本就只能先通过看具体的页面，然后在看对应的代码引用了那些组件，并逐一分析哪个组件对应的是哪个模块。这是个很头疼很麻烦很费力气的工作，一般这种情况下，大多数开发宁愿选择自己重新写一个。久而久之，便会出现多个功能相同的不同组件。更要命的是当又换一轮开发人员后。

再接手的开发看到这种情况，那可真是够折磨人的。

2.项目架构方面

目前前端架构主要可以分为两种

1.用目前市场成熟的脚手架二开项目，比如adnt design pro、element-admin等
2.自己动手搭建项目，并根据自身的理解对各模块进一步封装（单纯依靠vue或者react脚手架生成的项目架子的同学，手可以放下了）。

这里先不讲两者之间各自的优缺点，有一个很重要的区别是:
第一种会有相当规范且详细的文档介绍
而第二种通常依赖于开发之间工作交接时的口头讲解（运气好的话，可能会有人给你讲(￣_,￣ )），或者开发自己慢慢看代码理解。

比起不同的代码风格，出现与原本架构设计理念不符的操作更要命。举个例子，在项目架构设计之初，我们计划根据业务分类，模块化管理路由，结果新来的同事不知道，以为你只是多分了几个文件夹，于是他经手的需求，路由不分业务类型，都放在一个模块内。后面的同事看到两种规则，该如何选择？项目架构日后的走向就是个未知数了。
规范且详细的文档相当重要，不要将项目架构的走向依托于开发人员自身对代码的理解能力之上。

3.代码方面

代码注释这块是老生常谈的问题了，若说程序员最不喜欢的两件事，那必然是自己写注释和别人不写注释了。

友好的代码注释会很好的帮助后期代码维护，别人可以更快的寻找到关键代码，避免阅读无关的代码逻辑。

“请不要用注释来侮辱我的智商，但也不要用代码来考验我的眼力”

// 声明一个变量
const size = 10

比如上面这种注释就大可不必了....
大部分情况下只需要在关键的代码上注释其的作用即可

/**
* 判断用户是否为外星人
* @param user { Object } 用户信息
* @return { Bollean } true:外星人,false:不是外星人
*/
function isAlien(user){
      我是很多很多且抽象的代码....
      // 某些关键注释
}

3.有问题的前端团队文档规范落地

目前就本人个人从业经历来看，虽有几家公司前端团队是有一套文档规范的，但效果都不怎么样。
基本都是依托于wiki、腾讯文档等这种第三方系统来统一管理，整个公司所有部门产生的文档都在这里分类管理。且不说文档本身的可阅读性，光是这种文档“仓库”的杂乱程度就足以让一部分人懒得去打开系统并翻看此项目相关的文档。

且文档与代码过于脱离
并且对于组件管理这个概念来说，脱离于项目代码的文档是否能满足开发者的需求还是个问题。具体类比element-ui的文档，如果element-ui的文档是由图片截图和文字组成，失去了组件交互性，估计用户量怕是都要减少三成吧。

解决方案：本地文档系统

从两个层面来说：

1.项目架构方面的文档：
比如目录介绍、权限验证、路由模式、构建和发布、环境变量、开发规范、常见问题、等
例比element-admin官网文档
2.组件方面:
比如 项目中已封装过的组件例比element-ui官网文档

试想一下项目中有两个页面，一个像element-admin官网级别的文档用来描述自身项目架构问题，一个像element-ui官网级别的文档用来描述项目组件(可有组件交互性)。且都可在线编辑。

成果：

这是一个后台管理系统，在左侧菜单中除了有产品需求中的页面导航外，还有“项目指南”这个板块。项目指南是分别从架构设计，目录结构，公共组件...等多个维度来描述的文档。该文档由此项目的开发人员共同维护

项目指南中的页面只会在本地开发模式下存在，仅供开发人员阅读使用。build打包后的代码中，项目指南页面内的相关代码都不会存在。并且页面入口也只会在本地开发模式下存在。项目指南的内容是跟着git分支走的，不同分支的项目指南也可以不同。
文档支持在线编辑，分为预览区和编辑区，并且可以引入真实组件，产生相应的交互效果

1.从零写一个文档页的成本？

如图二中的文档内容，甚至都不需要花费一分钟的时间就可以完成。

2.在项目中集成这样的文档系统是否大题小作？

答案是值得的，这套架构我已经在四五个项目中试验过了，效果还是十分显著的，尤其是在新同事接口项目的沟通成本上。且在项目中公共组件的开发配合上会更加流畅。

3.在项目中开发此文档系统成本？

这个的确是需要一定时间的，本人从设计到落地大概总共花费了将近一周的时间，其中设计花费了大量时间思考。

4.难道每个项目都要再集成开发一个文档系统？

从架构角度来考虑，一个公司想要有技术积累，那必然要有自己的技术架构，不可能每个项目都是重新搭建或者采用市场上的二开模板项目吧。这个文档系统适合开发自己公司模板项目的场景，一劳永逸，后面项目都采用此模板项目进行二开，并持续收集意见维护。

5.具体实现思路以及涉及的技术栈

首先我们需要确认一个前提，这个文档系统是给开发人员看的，不能影响正常的产品页面，甚至在build构建好的包里，都不能看见任何一个文档系统内的东西，不能因为文档系统的代码影响build构建后的包代码体积。查看详情

1.需要封装一个markdown编辑器，并在ctrl+s保存时调接口持久化保存
2.接口我们采用nodejs,后端框架可以自行选择.在接口中将文档内容存为本地文件
3.nodejs服务是和本地项目集成在一起的，(写过nuxt的同学应该更能理解)。如下图

4.修改原本项目的启动命令，使同时启动vue项目和nodejs服务（做了自动分配端口，支持同时多开项目） package.json

"scripts": {
    "serve": "concurrently \"node src/server/index.js\" \"vue-cli-service serve\""
  },

5.做差异化打包，避免文档系统影响构建后的项目代码
6.定义.vue文件并引入markdown编辑器,注册路由。
7.优化第6步，第6步中的内容可以搞一个自动化，一键注册之类的。
8.至于路由入口可根据项目设计自行封装为导航，我是做了一个根据路由自动生成菜单的组件。

6.为什么没有具体实现教程或代码

想要自行搭建一个好的项目架构，需要有一定的架构设计能力以及相当的代码基础。根据我提供的思路实现出更好的版本不是问题。如果我把详细代码教程贴出来，就算大多数人能实现，但是没有相应的架构能力，后面恐难以维护，那还是不要的好。
还有一个原因就是，目前我认为还不够完善，至少，在我这里是还有可提升的空间的。但仅如此，这个架构中的文档系统在本人公司就已经开始发挥不小的力量了。
等此架构更加成熟完善后，或者看评论区的意见，会考虑放在githup上开源(仅是文档系统的demo，与公司项目无关)

7.仅是该架构就能解决所有问题吗？

这个当然不可能，任何好的工具都需要合理的使用，如果能配合上前端团队自身规范的执行，那将是如虎添翼。但是如果只是一个人想要推行前端团队的规范，且当你还不是lader，不能说不可能，只能说十分艰难！