畅享博客 > 天涯若比邻·sarria > 术业有专攻 - IT项目管理 > [讨论]程序员到底需不需要写文档?
2007-2-6 13:39:30

[讨论]程序员到底需不需要写文档?

程序员需不需要写文档?

 

目前手头的项目是一个代码外包的项目,承包方根据我们的需求提供设计方案和代码实现。目前项目处在系统实施阶段,经常会根据业务部门的要求对系统的功能及试用过程中发现的BUG进行修改。在修改过程中,经常会出现这样的情况:为了修复一个BUG而作的修改,可能在以后的使用中引发更多的意想不到的BUG,而当其引发的新BUG出现的时候,程序员却无法追溯到上次修改BUG时的纪录,只好凭记忆和经验去猜测,或者只好将所有相关代码全部重新检查一遍。

 

其实,这种情况很容易避免,只要开发人员在修改BUG时填写《试运行问题修改记录表》这种类似的记录文档即可,但,可惜的是,承包方的程序员似乎并没有写文档的习惯,因为按照他们的想法,项目组是应该有专门的人来编写文档的,而即使项目组目前没有这个编制,那么编写文档也不应该是程序员的责任,正是这种认知造成了前面描述的混乱情况。

 

那么,程序员到底需不需要写文档呢?如果需要的话,该编写哪些文档呢?欢迎大家一起来讨论!

 


推荐到鲜果: 查阅更多相关主题的帖子: 项目管理 开发文档

评论

按照我的看法,程序员的首要任务当然是写程序,这是毋庸质疑的,但,一个优秀的程序员之所以区别于其它普通的程序员,重要的条件之一就是在项目结项时,除了可以交出漂亮的应用程序代码之外,还可以拿出一套漂亮的文档作为代码的补充,比如:组件清单,算法说明,代码注释,业务逻辑物理实现图等等,以及清晰明了的工作日志、BUG修改记录表等日志性质的工作文档,这些文档对项目的实施、维护、及以后的升级改进都是至关重要的。而这些代码之外的工作产品以,正是一个优秀程序员的优秀之所在。 一家之言,欢迎讨论。

发布者 sarria
2007-2-6 13:40:29


没听说过什么试运行问题修改记录集,每天改十个Bug,如果加上写这玩意儿,最多只能修改5个了。 实际上,现在的项目管理工具可以自动生成,所有的函数加上注释就可以了,包括每次的修改记录都放到注释里,然后用工具就可以生成完整的像MSDN一样的文档。 如果按照原始的项目管理方法,应该是先把需求修改写到需求变更文档里,然后通知程序员去根据这个文档来改程序。这样岂不是更慢?你有专人维护这个文档吗?而且维护这个文档的人需要同时了解需求和代码(当然,对代码不需要太熟)。

发布者 Jason Cui
2007-2-6 14:13:06


对于一个IT项目来说,只有代码是很危险的,尤其是对团队开发的项目来说,没有设计、开发方面的文档,系统地维护和升级将是十分困难的。 写文档一定会占用编程的时间,但是有些文档是绝对不能少的。当然,我们可以根据项目的具体情况对相关的文档进行裁减,既不会占用太多时间而影响开发速度,也不会最后交付的产品只有代码。 具体以修改BUG为例,我更倾向于开发人员在完成每个修改之后,随手将修改的内容记录下来,可以只是一个简单的excel表格即可(参见附件),这样自己和其它的开发人员对于每个修改点都可以轻松的找到修改记录,当项目需要Review或升级时就显得非常有用了,比直接看代码效率高得多。 当然,用工具直接生成代码说明文件很方便也很节省时间,内容也很全面和详细,不过,除了这样的文件之外,开发人员工作当中的日志型文档无论是对程序员自己还是后来的维护人员来说,其重要性也是不可忽视的。
snap.jpg ( 63 KB )

发布者 sarria
2007-2-6 15:56:46


我的天,直接记Excel?!你不是程序员吧?

发布者 Jason Cui
2007-2-6 16:37:17


我是程序员,这点不用怀疑,呵呵。 excel记录的是工作日志,属于管理类文档。作为一名程序员,除了技术类文档之外,适当的也要写一点管理性文档,不然写出来的代码只能是个人的,而不是组织的。 项目经理有时候需要从项目和组织的角度出发,要求程序员记录一些东西,而不仅仅是要求按时提交代码。比如在外包项目中,我会要求承包方的开发人员每天提交工作日报,每周提交工作周报,在项目实施阶段,要记录下来每次修改的功能说明。

发布者 sarria
2007-2-7 9:20:24


就算记管理类文档,也不能用Excel这种东西记,最简单的是用文本文件,高级一点用XML文件。否则,版本控制软件无法识别版本修改记录。

发布者 Jason Cui
2007-2-7 9:44:09


写文档是必须的,没有文档的代码基本就是废物!!!

发布者 mrmaomao
2008-2-2 15:48:26


您正在以 匿名用户 的身份发表评论  快速登录
(不得超过 50 个汉字)
       看不清,换一个
提示消息
(输入完内容可以直接按Ctrl+Enter提交)