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

原创 2006年06月04日 01:13:00

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

相关文章推荐

OCR文本识别系统项目文档——欢迎探讨交流

《OCR文本识别系统项目计划书》 一、作品概述 http://115.159.205.168/ocr_php/public/index.php 本项目的名称为OCR文本识别系统,研发其主要目...

java 小型游戏项目(文档与源代码)

  • 2009年03月08日 21:10
  • 1.25MB
  • 下载

游戏设计的艺术:一本透镜的书——第二十四章 团队往往通过文档交流

这是一本游戏设计方面的好书 转自天之虹的博客:http://blog.sina.com.cn/jackiechueng 感谢天之虹的无私奉献 Word版可到本人的资源中下载 第二十四章团队...
  • tiewen
  • tiewen
  • 2015年06月29日 09:26
  • 573

java小型游戏项目(源码+文档)

  • 2011年03月18日 13:33
  • 1.26MB
  • 下载

人事档案管理系统总结(二)---用文档和客户交流

2013年8月21日,又有一次去人才市场给客户发布了人事档案管理系统,但是这一次去 不在是以前那样带着沉重和害怕的心情去了。这次去是带着轻松的心情去了,因为是带着开发 小组人员一个多月的辛劳汗...

小型交流伺服电机控制电路设计

  • 2014年08月07日 12:04
  • 18.42MB
  • 下载

软件设计交流系统-用户手册与帮助文档

用户手册与帮助文档 1        引言 1.1    编写目的 本文档为指导用户如何使用软件设计交流系统而编写,为用户详细介绍本软件产品,并给出清晰明确的操作指导。 1.2    背景 ...
  • playeye
  • playeye
  • 2012年06月12日 19:27
  • 797

Ajax内部交流文档

====================================================== 注:本文源代码点此下载 =============================...
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:在小型项目中的交流与文档书写
举报原因:
原因补充:

(最多只允许输入30个字)