记录软件项目的好方法和坏方法有哪些？

Question

我负责找到一个很好的方法来记录我正在进行的软件项目.

记录哪些内容很重要？代码和设计的文档是否应该以注释的形式出现在代码中？我们应该将文本文件或Word文档直接放在源代码控制中以便与代码一起使用吗？我们应该使用维基吗？

要考虑的因素包括当前团队创建文档的难易程度,以及其他开发人员以后查找,更正和扩展文档的难易程度.我从许多项目中获得的经验是开发人员倾向于不编写文档,因为编写文档的系统过于复杂或开发人员不友好,而且几年之后,新开发人员很难找到编写的小文档.

我对您在类似项目中使用的方法感兴趣.什么运作良好,什么运作不好,为什么？

关于该项目的一些关键事实:

• 该平台是C#和.NET.
• 我们使用Visual Studio和Team Foundation Server进行源代码管理和工作项(任务)管理.
• 我们使用Scrum和测试驱动的开发,并受到域驱动设计的启发.
• 该软件包含一组Web服务和两个GUI客户端.
• 其他客户将来会与Web服务集成.集成将由其他团队的其他开发人员完成(因此Web服务形成一种API).
• SharePoint在整个开发环境中被大量使用.大多数项目都有SharePoint站点,包括我们的站点.
• 在我们项目的SharePoint网站上,我们目前有大量关于需求,设计,利益相关者演示等内容的MS Office文档.保持最新状态很难.
• 我们还为开发团队提供了一个SharePoint wiki,我们在这里以非结构化的方式记录事物.示例包括我们的构建脚本是如何组织的,我们的测试策略,编码指南.
• 该软件是一个相当大的金融机构的内部应用程序.
• 该软件由一个由6人组成的团队在约1年的时间内开发.
• 开发人员只是为此项目雇用的顾问,将来无法提供帮助(除非客户决定支付费用).
• 客户对如何记录此类项目的指导方针很少.

Answer 1

对我来说最糟糕的是缺少文档是文档过多.

请记住,是的:记录您的项目非常重要,但文档的主要部分始终存在从未被读过的风险.

因此,我认为一个好的起点在于考虑您的文档更像是您可能用于向项目中引入新开发人员的内容,而不是对软件内部工作的详细描述.

Answer 2

我认为最重要的事情是决策.这适用于从需求到架构选择的所有内容.模块X的要求是什么？这些要求如何在架构中体现？你为什么选择建筑模式A而不是B？有什么好处？对于源代码也是如此:众所周知,评论为什么比如何更好.

在我看来,如果你使用Wiki或者用Word制作的需求文档,你如何记录这些决定并不重要.更重要的是,这些文档始终是最新的,任何人都可以轻松访问它们.如您所说,这可以通过使用wiki或将文档置于源代码管理下来实现.如果只有少数人可以访问它们,则更有可能不会更新,不必在必要时阅读.

我们将Wiki用于我们当前的项目,并且效果非常好.任何人(开发人员,经理和客户)都可以轻松访问,历史记录可以跟踪更改,因此您可以了解已更改的内容和原因.此外,我们尝试以有意义的方式记录代码并记录主要的设计决策.我们尽量不要记录太多,例如小事,因为总是很难让这些事情保持最新状态,并且不值得努力,imho.

Answer 3

天儿真好,

绝对使用维基.我推荐TWiki,因为它是一个优秀而广泛的维基实现,而不需要太复杂的安装和管理.

这里有几个初步的想法.

分类:

首先介绍一下你想要捕获的内容,但是

• 允许人们根据需要添加新类别或子类别,
• 允许人们根据需要重新命名(子)类别,也许可以按照这个类别进行重新分类,这样你就不会因多个名字的碎片而得到基本相同的碎片.
• 让任何初始(子)类别枯萎,如果它们留空则死亡.在项目结束时执行此操作,因为某些区域可能只有项目结束时的条目.

标记:

开始使用标签云.BTW这是一个出色的插件,可供TWiki在项目早期开始对内容进行分类.改装标签几乎是不可能的.提前开始标记还允许人们搜索可能已存在的信息,而不是在多个位置具有相同的信息.

HTH我会回来并在我想到它们时添加更多积分.

Answer 4

首先也是最重要的一点，以 NDoc 可以解析的方式编写注释。这是记录代码本身的最佳方式，因为开发人员几乎不需要改变他们的开发实践，并且您可以生成解释代码的页面，而无需查看代码。

其次，让开发人员编写文档并不容易，而且让他们这样做可能是徒劳的。这就是像Fogbugz这样的产品发挥作用的地方。他们将帮助通过票证管理开发，帮助跟踪签入，并在完成迭代后生成发行说明。

总之，最好的选择是找到适合开发人员现有流程的最有效的解决方案。如果它对他们的开发过程影响很小，他们将更有可能采用该系统。