在小型项目中的交流与文档书写

    刚开始做软件的时候，就是自己一个人，当时也不知道什么软件工程，文档肯定是没有的，但是注释还是写的了，但是随着软件的发展以及新项目的开展，等到需要回头维护的时候，也只能记得个大概，需要重新仔细推敲一下代码，才能完成维护任务，并且还会发现注释有时候甚至是错的，因为没有随着代码的发展同步维护。
    慢慢的自己开始带团队了，在实践中发现确实需要引入软件工程，于是尝试过各种软件过程，比较简单适合小型团队的应该是敏捷过程吧，而且还是比较容易入门的，容易看到实践成果。有的过程学习曲线比较陡，团队培养成本偏高。当然，各种软件过程我觉得可能都是殊途同归，在软件过程背后都是设计的几个原则。
    这里要说的主要是文档的问题。我认为最好的文档就是代码，其它的文档通通都是辅助性质的，以最终的代码为准。
    在大的框架设计上面，为了方便团队成员理解，当然应该画些示意图，什么工具都可以，本人比较喜欢的是rational rose，不过有时候觉得又不准备实践RUP，装个3个多G的画图软件真的是浪费啊：）但是示意图可能会与最终代码有出入，我觉得示意图能反映框架精神就可以了，没必要再花精力来同步，当然如果有自动的同步工具那肯定更好。
    对于具体的功能代码，文档依然是代码，根据测试驱动的方法，对具体的功能都尽量给出测试代码（不是每个功能都需要测试代码，这个需要灵活掌握），测试代码是对代码质量的检验，同时本身也是功能代码使用方法的函数。同事看了测试代码很容易就明白了功能代码的使用方法以及目的。如果测试代码难以看懂，我们就认为测试粒度可能过大或者设计不够清晰，所以测试代码也可以检测框架设计或者代码书写的科学性。
    上面讲的是同一个开发团队内部的交流。随着公司的发展和成长，出现不同的职能部门是意料之中的事，如果出现多个部门合作的项目，那么我依然坚持认为最好的文档是代码。
    之前做了个项目，就是由我们软件部门和硬件部门一起开发的，硬件部门提供底层的规则，我们则负责在硬件上开发。硬件部门由于不熟悉程序，于是提供给我们的底层规则都是用doc文档描述的。当我们需要使用的时候，首先要研读文档，由于文档表现能力终究有限，有不少地方难以独立理解，那么就需要和硬件部门沟通，硬件部门可能又需要回想一下才能给我们解释清楚。另外也会有因为对文档理解有误产生的效率损失。这里可以看到，部门之间运用文档交流的缺点：硬件部门实际把工作分成了两部分，一个是规则开发部分，一个是规则转换成代码部分，第一，这两个工作不能一气呵成，中间有一定的时间跨度，对于精确理解规则带来了记忆力的因素，第二，规则要转换成代码，需要软件部门和硬件部门的合作，两个部门在地理上有一定位置，交流成本增高影响软件开发进度。
    上面提到的项目，我是作为软件部门的负责人，对于交流成本我估计不够充分，事后计算，交流成本可能花费了7天左右的时间，而实际项目时间不过40多天，可以看到这种交流成本相当的高。
    鉴于上面所说的情况，之后的一个类似项目里面，我坚持取消doc文档，一定要用代码作为部门之间的交流文档。我在软件部门把规则相关的代码全部剥离出来，以lib的形式来联接，然后把lib的撰写任务分派给一个程序员，由他入住到硬件部门，和硬件部门一起完成lib代码，并且建立对此lib的测试代码。这样软件部门得到的lib直接就是可以实现底层规则的，并且测试代码明确的说明了如何使用。虽然此项目目前还没有完成，但是就现在的进度而言，交流成本非常低了，软件质量也有了提升。
    我没有参加过10人以上的项目开发，随着人数增多，是不是会有对文档的强烈需求我就不得而知了，就我目前实践而言，用测试代码代替文档是相当可行的一个交流办法。欢迎指正和讨论。