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

Question

我负责找到记录我正在进行的软件项目的好方法。

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

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

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

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

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

Answer 1

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

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

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

Answer 2

对我而言，最缺乏文档的是过多的文档。

请记住，是的：记录您的项目非常重要，而且文档的主要部分始终存在从不完全阅读的风险。

所以，我认为一个好的起点在于考虑您的文档更像是您可能用来向项目介绍新开发人员的内容，而不是对软件内部工作的详细描述。

Answer 3

天儿真好，

绝对使用维基。我推荐TWiki，因为它是一个优秀而广泛的维基实现，而不会太复杂，无法安装和管理。

以下是一些初步想法。

<强>分类

从您想要捕获的内容的初始本体开始，但

• 允许用户根据需要添加新类别或子类别，
• 允许人们根据需要重新命名（子）类别，也许可以按照这个类别达成一致，这样就不会因多个名称的碎片而产生基本相同的碎片。
• 让任何初始（子）类别枯萎，如果它们留空则死亡。在项目结束时执行此操作，因为某些区域可能只有项目结束时的条目。

<强>标记：

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

HTH我会回过头来添加更多积分，因为我想到了它们。

Answer 4

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

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

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