文档与团队

Utensil按： 此文是我在renny的博客实习回来，说说心理话 的回复，讲了个人对文档与团队的一点粗浅理解。现在放到自己的博客里来存个照。

 

文档

 

关于文档的重要性，我说一个自己的经历：

之前为某外国开源类库写一个实用工具，有两个core developer review，往来都是e-mail沟通，但基本上是一个人写的，但在核心功能实现之后，我由于时间原因不得不搁置下来，我最后就用Doxygen给软件 写了非常详尽的文档，说明了设计思路、可扩展的开发接口、存在的问题以及TODO等等。我搁置很久之后，那个对我工作了解的最少的core developer轻松地接手了维护。

我这样做是因为我深知：

这个实用工具，如果没有为它的核心类写份文档，在我停止开发之后，最有可能的命运就是因为维护问题而从类库的util中消失，或者变成别人写的新实现，而他们却无从了解旧设计在产生过程中所遇到的实际问题以及相应的适应性改变，要提炼出一个更好的设计会更困难。

文档是软件生命的有机成分，能在作者离开后延续它生命，原有的经验和代码得以重用，或对新的设计有启发。而光溜溜的源代码，可能在环境变后都无法编译了，可能时过境迁自己都理解不了了，又有谁来试图理解和维护？曾经花在上面的心血，就此白费。

解耦的确是写程序中非常重要的一环，但是内聚所代表的“把相关的内容尽可能集中，方便理解和维护”，在实际编程中更难做到。而文档在这上面能有一定帮助。

写作文档的过程也是一次清理接口和重构的过程，因为如果接口设计得不好，文档写起来就非常困难，非常冗长。可以以“好的代码不需要注释和文档”的思想来指导编码，不过不能因此而觉得文档无用。

强调文档重要性，不是个学院派的唠叨，实践中挺重要的，就像单元测试一样，没有，始终是个致命伤。

 

团队

关于团队的问题，的确是一个很令人头疼的问题。

在学校里，能者往往居组长，组长往往变苦力。这其实是团队非常原始的形态，可惜这样一种原始的形态仍然不断在实际工作中重现、定型、死循环化。这种形态的另外一个变种是组长是甩手掌柜/催命神，副组长做苦力。

和很多同学相比，我并不是一个有很好组织能力的人。但大学四年，一个很重要的收获，就是在一次次做组长的团队中，每一次和前一次相比，我都更从苦力状态中挣脱出来，团队也更从孤立单干、陷于碎片的状态中挣脱出来。

并 不至于变成了甩手掌柜，我仍然把握住最为核心，某些事情团队中只有我才能做好的事情，我依然自己完成，但一次比一次剥离出去让组员做的事情更多。到后来， 我手上不会再有劳动力密集型的工作，工作量也成了团队中最少的，但我却能更好地调动团队，让他们去做他们有积极性做的事情，而这些事情能为我省不少心，同 时又充分发挥了他们的特长和能力，保证了进度和最终的质量。

早沟通，早让他们参与其中，以及自己心中预先对不同难度的各种任务的分布有个 基本的概念，有些人可以一直参与做个了解状况的闲人，后期可做预备队来解燃眉之急。如果有同学技术不行，我会制造给他一种项目需要他的力量的感觉，让他紧 迫起来，不至于觉得自己什么事都做不了，什么责任都不用负，也就毫不关心。至少他会在项目期间试图去学一些相关的基础知识，如果了解项目，后期调用他，他 也能有相应的功能，呵呵。

而且远在了解敏捷开发的结伴编程之前，我在宣传部就用了结伴的管法。每一张海报，都由两个人完成，其中一个指定 为主要完成海报的人，因为PS这个事情本来能合作的就有限。另外一个人其实对这张海报什么都不用做，（往往有另外的任务在身），但会需要督促前者的进度， 在前者陷入审美困境的时候给他建议，闲下来也可以做前者的助手。如果进度和质量不过关，两个人都要负责。

这个管法是从我自身的工作效率低 下的体验中总结出来的，因为我会把正事搁到最后一刻加班做，之前的设计酝酿阶段和找资料阶段往往因为一点不知方向在何就停顿下来。因为做海报，特别需要灵 感和方向感。一个人做的时候我往往感觉到需要另外一个人和自己一起才带劲。所以在管团队的时候，我就用了这个办法，把这另外一个人制度化。

当然，这些措施也未必有效，说下自己心得，与博主分享，欢迎大家指正。

 

 

 

评论

1 楼 liugf 2009-08-06  

期待跟多好文章！