如果怕忘记无法维护，那么我对注释的理解，以及使用Flow

[rhinel]

经常遇到这种情况，一个项目1个月以上没有关注维护，那么连开发者自己都不记得怎么回事了。

“这是啥？这结果怎么出来的？这是哪里配置的？”

然后就是无尽的搜索变量名，查引用……甚至不清楚改完会不会影响到其他地方。

蛋疼至极。

时间久了别说整体的持续优化了，修改功能都是一件很复杂的事情：

1. 工程项目让引用嵌套变得更加复杂
2. 没有自动化测试、或测试不能完全覆盖

在这种情况下，不可维护性甚至比以前web2.0时代更甚。

注释

有一个笑话：工程师最恶心的事情是：项目没有注释，第二恶心的是：写代码还要写注释！

现在大多数工程师都不喜欢写注释，跟理工教育下文章写的不好，甚至不愿意多写文字有关，很多人都说，代码写的好，代码就是注释，我觉得：代码只能表示具体逻辑，仍然需要注释（文档）来帮助快速明示代码设计。

个人觉得，如果注释能够通过下面这些检查时，基本上项目可维护性就会非常高了，同时写注释的过程中会使得开发者对项目本身设计模式产生更多思考，更容易对项目进行改进。时间——这俩字删掉不要发

项目配置

几乎所有的项目（事项），都会按照人类工作发展的这一成熟模式去实行：抽象、模块化、分工。项目小到一个领导突发奇想H5，到大型渐进式项目，及不同层次不同阶段解耦合并的多维度项目，大多都是遵循这一模式。

无论什么项目都不愿自己是一次性产品，那么一个基业长青的项目必定有自己的更新及维护模式，一个好的注释（文档）不仅能够一目了然，还能像树一般寻根见底，维持整个项目的初衷。

1. 已有package记录项目依赖，建议仍有一份md分类说明依赖的作用及版本控制说明。对非源管理的依赖更要注明摆放位置及文档地址；
2. 支持的执行环境说明：构建环境、包管理器、运行环境、执行说明等（该类大多写在readme）；
3. 项目配置：项目框架需要的配置文件，在其中丰富说明及文档地址；如有用到babel、postCss、lint、环境参数、自定义版本控制等，均需要进行说明；
4. 构建配置：编译说明、CI等等；
5. 开发配置：开发参数、编辑器要求等等。

以上内容需要在项目基础文件中进行清单。

组件及组件关系

开发型项目则需要有组件清单，或者目录结构，至少方便贡献者知道怎么去查找文件。

应用型项目就不同了，应用和具体需求有直接关系，需求都是广泛的、复杂的，甚至有许多匹配特殊环境和目标受众的，没有相关背景的人根本无法理解为啥这么设计，甚至脱离需求上下文，都无法理解，因此该部分注释更加复杂。

1. 功能路由配置：某个路由可能代表一类功能，可能代表具体功能，包含路由参数等，需要标注；
2. 全局状态配置：嘿，大型项目一定会走到这一步的，甚至我建议标准项目都配置这部分内容，主要用于功能切换中的权限控制，或者在路由中处理各种前置功能；
3. 运行参数配置：在具体项目中，此配置更多和ajax有关，包含后台沟通及前台标识，大多数和ajax配置写在一起；
4. ajax配置：统一的请求封装；
5. 本地存储配置：token、id等等，防止同源污染，storage建议增加[pre]key前缀；
6. CSS命名分配：JS命名基本由模块化处理掉大部分问题，小部分可通过命名规则处理。但CSS的特性使得必须分配命名规则，组件中、模块中、视图中等等，相应需要注释来明示相关规定；
7. module配置：清单、功能说明、参数要求、示例、依赖要求等，提示：不要相信调用传递的参数，module内部需要进行校验。

代码逻辑

现代框架均优化编写体验，在框架主张的编程思想下，代码都很清晰的展示了执行逻辑。

但是！前面说过了，逻辑的原因脱离背景就没人知道了，很可能一个微小的特殊处理，引起用户的巨大不适应……然后，死都不知道怎么死的。

1. 依赖说明：这个非常重要；
2. 主要功能逻辑：必须说明干嘛的，有几个API点；
3. fun处理目的、输入及输出：这个大家都觉得命名就能说明一切，但是……；
4. 变量：类型、说明，是否有绑定内容、proxy等等；
5. 特殊处理：这个很重要啊，比如处理vue.$nextTick的坑，react事件未卸载dom没了的坑……。

FLOW

Flow 是 facebook 出品的 JavaScript 静态类型检查工具。

为什么要上Flow，俗话说得好，动态一时爽，重构火葬场……

调用函数的时候，如果函数做了参数检查还好一点，改改就行；如果没做……出BUG：是TM打开方式不对还是用的不对还是函数有问题……陷入无限debug中……这只是原因一。

基于历史原因还是什么鬼，JS是动态类型语言，在计算前完全不知道这个变量可能是什么类型，然后完全无法优化编译。

然后各大浏览器使出浑身解数，不知道我就猜，猜错几次就算了，老老实实该怎么执行怎么执行，这就是JIT技术。

很多运算速度就会卡在这些地方，在大量计算上速度可能会差几个量级。

既然JS已经这样了，所以TS应声而出，获得一致好评，还有通过其他语言编译成JS的比如Dart、Go等，基本目的就是写更优秀的代码。

但是这种基本算换语言了，对既有项目只剩下重构了（火葬场）。

Flow算是一种很好的选择和过渡，大家还是用原味JS编程，对原有项目侵入较小，付出不高的成本对代码质量有很大对提升。

特殊的Vue

Vue项目使用Flow，收益并不明显，反而增加复杂度、无法对整体结构有统一处理：Flow静态类型检查及在Vue项目中的使用。

其他框架

NodeJS、React基本都能上上上……，如果能够TS更好了……

其他

WebAssembly 打算把JS完全换成另外的语言，并且不用编译，只能说期待吧……

项目维护基本思路

to be Continued