从文案工作反思软件代码质量

最近一段时间，和客户方的一位技术文案部的员工一起合作编写软件产品的API级别的文档，用于给第三方开发人员对我们的软件产品进行插件及二次开发。

总的来说，工作量相当大。一个原因是因为已有的API文档非常陈旧，里面的内容长期没有维护很多都需要重新编写；另一个重要原因则是我们的代码质量不够高，导致对API行为的描述非常困难。

我一直觉得，文档的编写应当是“准确”且“简明”（所以我不太喜欢阅读内容繁杂的API文档）。“准确”自当不用多说。“简明”可以让文档更易读易懂。如果想要保持文档的易读易懂，那么API级别的函数或者类的行为就不应该过于复杂，应该单纯一些，分支行为少一些。或者即便有分支行为，也应当能用表格等形式清晰地表达出来便于查阅。

可是，由于我们项目中的开发团队长期对代码质量重视不够，以及为了解决最终用户碰到的问题而引入了很多special logic，最终导致API级别的函数、数据结构和类等逻辑会出现不一致(甚至冲突)，或者special logic过多。这直接导致：为了将函数、类等行为描述准确，我们不得不重新检视所有代码、考量所有分支。这样的工作占据了非常多的时间，直接导致我们进度缓慢(经过粗略统计，编写一个API函数或类的平均时间在1.5到2个小时)。而且因为存在很多special logic分支，导致描述文字臃肿。更糟糕的是，很多作为参数的数据结构中也包含很多为special logic所设置的特殊成员——在正常的业务逻辑下是根本用不到的，只在一些很corner的case中才会被用到。但是由于某些原因，他们被直接包含到了数据结构中，使得我们也要写大量文字来解释这些特殊成员的用途和意义。

除了上面这些问题，另一个突出的问题就是代码注释的缺乏。很多代码——比如一些非常重要的常量定义或者数据成员定义——没有完善的注释，而在长期的工作中曾经编写这些代码的开发人员已经流失掉了，导致我们现在不得不花费大量的时间去重新学习和理解这些代码。而客户产品所涉及的逻辑和业务繁多，我也并没有参与过所有的业务开发，使得学习非常吃力，今晚不得不给客户方的开发人员发邮件求助了。

今天加班到很晚才回家。回家前，我对和我一起编写文档的同事说：软件的逻辑和行为的一致性和良好的代码注释真的太重要了！ 不在编写文档中实实在在接收一次教训，真的对这两点体会不深！以后的工作中要非常注意这两个方面了。

虽然最近文档编写工作让自己很痛苦，但是，它毕竟让我接受到了上面两点教训。长远来看，这是促进我进步的好事！而且，在编写过程中，我还深入学习了很多产品代码和业务，对软件的了解又加深了一层。和客户文案员工的合作，也让我多少看清楚了开发部和文案部之间的工作关系及协作方式。它也让我体会到：作为一个开发人员，文档工作其实一直是必不可少的——至少代码注释就是一种文案。适当做一些文案工作反而可以督促自己注重提高代码质量——给自己写写文档，就知道自己的代码有多糟糕了。