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

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

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

网站项目标准文档格式模版---网站项目建设流程概述(转)

 网站项目标准文档格式模版---网站项目建设流程概述(转) 一.概念 网站项目管理就是根据特定的规范、在预算范围内、按时完成的网站开发任务。 二.需求分析 项目立项 我们接...
  • kaloha3
  • kaloha3
  • 2014年04月22日 23:24
  • 3839

IM聊实现客户端之间信息交互需求文档

终于放假啦~之前学习太忙很多知识点都没有写博客,可能自己学会了但没有分享给大家,接下来几天我可能把一些学过的东西整理成博客发出来供大家相互学习交流。 ...
  • pan861190079
  • pan861190079
  • 2016年06月24日 10:37
  • 1292

软件项目开发的文档编写标准化

软件项目开发的文档编写标准化   在项目开发过程中,应该按要求编写好十三种文档,文档编制要求具有针对性、精确性、清晰性、完整性、灵活性、可追溯性。    ◇ 可行性分析报告:说明该软件开发...
  • xuqiang918
  • xuqiang918
  • 2014年04月10日 16:11
  • 6390

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

《OCR文本识别系统项目计划书》 一、作品概述 http://115.159.205.168/ocr_php/public/index.php 本项目的名称为OCR文本识别系统,研发其主要目...
  • chudongfang2015
  • chudongfang2015
  • 2016年10月29日 16:58
  • 1005

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

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

java++小型游戏项目(文档与源代码).可用做毕业设计

  • 2009年04月01日 14:19
  • 1.26MB
  • 下载

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

  • 2010年06月17日 21:30
  • 1.26MB
  • 下载

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

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

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

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

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

这是一本游戏设计方面的好书 转自天之虹的博客:http://blog.sina.com.cn/jackiechueng 感谢天之虹的无私奉献 Word版可到本人的资源中下载 第二十四章团队...
  • tiewen
  • tiewen
  • 2015年06月29日 09:26
  • 609
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:在小型项目中的交流与文档书写
举报原因:
原因补充:

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