记录现有代码库的方法

我作为团队的成员在没有内联文档，也没有技术文档的现有应用程序上工作。当我一直在处理应用程序的各种错误报告时，我为自己写了一条面包屑的痕迹-各个地方的错误号，以便下一个开发人员可以参考该错误号以查看发生了什么。

因此，我的问题是：

记录此代码的最有效方法是什么？我应该在接触该区域时记录下来（如果需要，可以使用病毒方法），还是应该自己从每个部分进行记录，而不遵循分支到应用程序其他区域的路径？我应该在以前不存在的地方插入行内注释吗（担心我最终可能会错误地识别代码的作用）？

您将使用哪种方法来准确，快速地为没有现有内联文档或内联引用外部文档的大型应用程序提供文档？

记录旧版代码库

我强烈建议您使用旧有代码库遵循侦查规则。试图独立于遗留项目而对其进行记录是永远不会发生的。

代码内文档

最重要的是在您选择的开发环境中使用文档工具，这意味着python的pydoc，java中的javadoc或C＃中的xml注释。这些使得在编写代码的同时易于编写文档。

如果您依赖于以后再回来记录文档，则可能无法解决问题，但是如果在编写代码时就这样做了，那么需要记录的内容将是新鲜的。如果XML文档不完整或与实际代码不一致，C＃甚至可以选择发出编译警告。

作为文档进行测试

另一个重要方面是具有良好的集成和单元测试。

文档通常集中于类和方法独立进行的工作，而跳过如何一起使用它们来解决您的问题。测试通常通过显示它们如何交互来将它们置于上下文中。

同样，单元测试通常会明确指出外部依赖关系，通过这些外部依赖关系需要模拟出事物。

我还发现，使用测试驱动的开发可以编写易于使用的软件，因为我一开始就在使用它。有了一个好的测试框架，使代码更易于测试和易于使用通常是一回事。

高级文档

最后，还有关于系统级别和体系结构文档的操作。许多人会主张在Wiki中或使用Word或其他文字处理器编写此类文档，但是对我而言，此类文档的最佳位置也是与代码一起使用的纯文本格式，这是版本控制系统友好的。

就像代码内文档一样，如果您将更高级别的文档存储在代码存储库中，则很有可能使它保持最新状态。您还可以获得以下好处：拔出代码的XY版本时，还将获得文档的XY版本。此外，如果使用VCS友好格式，则意味着像代码一样，很容易进行分支，差异和合并。

我非常喜欢rst，因为它很容易从中生成html页面和pdf文档，并且比LaTeX友好得多，但仍可以在需要时包含LaTeX数学表达式。

棘手的问题。基本上，我将使用“重构”方法，我将其重声明为“如果您触摸代码，请对其进行记录”。

但确切地说，随着问题的出现，以及您必须熟悉该代码以修复所发生的错误，我想您应该利用这种熟悉度来对该代码编写注释。从本质上讲，修复该错误的动机是在那时迫使您对代码进行足够的熟悉以能够对其进行文档化。出于这个原因，我宁愿跟随不相关的分支，也不愿记录不相关的功能，因为在那一点上，如果您不对代码进行主动测试（以验证错误修复），那么很难完全确保您确切了解代码的作用以及原因。（我并没有遇到这样的问题：即使在测试错误修复程序时，也很难准确地找出代码的原因以及为什么代码会执行它的工作；

这种方法应该倾向于最大程度地提高准确性，但会牺牲整体速度，但又不会影响您同时过于严格地维护代码的需求。当然，如果您的错误修正职责很小，则可以冒险进入“未知领域”并在那里开始进行文档记录，但是，如果您（像我们大多数人一样）在一天中没有足够的时间来修复和记录代码，是一个很好的折衷方案。

还有一点值得注意。您应该具有良好的外部文档。您说您的代码没有引用外部文档。我希望为您着想，但是存在这样的外部文档。如果没有，我实际上将编写外部文档作为第一要务。我认为，对于所有大型软件项目而言，功能规范层面上的某些事情绝对至关重要。原因是功能规范或该形式的高级文档可以帮助防止任何软件中的“功能蠕变”或“功能漂移”。并且功能漂移（尤其是）可能会对文档造成破坏，因为它可能导致文档过时。（我将要素蠕变定义为将要素逐步（且烦人）添加到软件中；要素漂移另一方面，随着时间的流逝，软件采取的一系列操作会缓慢变化。特征爬取是附加的，即通常涉及增加软件功能的集合。另一方面，特征漂移为零和；一个接一个的边缘功能被定义为可以做一些不同的事情，直到软件所做的事情完全不同于最初的意图。功能漂移很少见，但对于文档来说却是致命的。）

我在两年的时间内共同开发的一个应用程序严重缺乏文档。在某个时候，很明显，我们将把该应用程序传递给另一个开发人员，该开发人员将从那时开始对其进行维护，因此我们必须记录代码。

为了处理文档编制过程的巨大范围，我会尝试在给定的一天将所有代码记录在特定功能或应用程序的一部分中。我没有特定的模式，但是坚持每天做一些事情，并通过每天记录整个文件或应用程序的一部分来获得完成感。

记录整个应用程序花了几个月的时间，但是每天最多半小时（它）并没有真正花在项目进度表上，并且避免了记录过程中的许多繁琐工作。

我们在C＃中使用了XML文档，它提供了足够的功能和结构来简化文档编写。即使您没有在编写C＃应用程序文档，也要先编写简短摘要然后再加上备注，这种做法非常有用。

我会在添加/修改代码时记录下来。除此之外，我还将记录公共API或模块之间的任何接口。如果要记录所有代码，则可能看不到所花费时间的投资回报率。在开发时，使用诸如Wiki之类的东西来组织外部文档可能会很有用。在上一个项目开始时，我引用的最有用的文档是体系结构文档。它包括有关所用技术的信息，并提供了有关应用程序分层方式的高级视图。

我会用Doxygen注释。Doxygen具有比大多数其他自由格式更多的输出格式，并且易于学习。

您甚至可以考虑聘请承包商来这样做，因为我们中有些人是以谋生为目的。但是，使用此选择，您仍然必须致力于查看文档。

另一种常见的技术是分配新的开发人员来记录代码。然后，让每个新手都可以快速入门。请注意，一些开发人员将其视为获得根管的工具-仅在直接情况下才需要LOL。

在开始记录任何内容之前，请制定一个标准。这可以很简单，只需确保在函数或类头上方写几行到更正式和冗长的内容（如javadoc）即可。在任何人都可以检入代码之前，他们的文档必须符合该标准。

我发现工作得很好的方法是，在我创建的以前未记录过的函数的函数标头之前添加写得很好的注释，并将行内注释添加到我添加的任何内容中。您要避免记录未涉及的代码。有不好的评论比没有评论更糟，如果您要“迅速”记录下来，您可能会写错评论。