自动生成代码文档是否有逻辑上的原因？[关闭]

可以使用多种工具来自动生成文档，其中GhostDoc是其中最著名的一种。但是，根据定义，它生成的所有内容都是多余的。它查看方法，类等的名称，并输出可能更详细地解释它们的英语。在最好的情况下，它可以完成读者头脑中已经可以做的事情（示例取自此处）：

/// <summary>
/// Initializes a new instance of the <see cref="Person"/> class.
/// </summary>
public Person() ...

在最坏的情况下，它最终可能会生成奇怪的文档，而这些文档实际上在试图启发性地弄清名称的含义时具有误导性：

/// <summary>
/// Riches the text selection changed.
/// </summary>
/// <param name="richTextBox">The rich text box.</param>
private void RichTextSelection_Changed(System.Windows.Controls.RichTextBox richTextBox) ...

似乎对GhostDoc的态度是，“本质上来说，拥有某种形式的 XML文档会更好”，但是当该文档100％冗余时，为什么呢？充其量只是在浪费大量的空间吗？

在我的工作场所，我们几乎必须始终使用GhostDoc的自动生成的文档来记录所有内容。您这样做是不是有合理的理由，如果您不想自己亲自编写文档，则不要简单地将代码保留在文档之外？

记录所有内容，几乎总是使用GhostDoc的自动生成的文档。您这样做是不是有合理的理由，如果您不想自己亲自编写文档，则不要简单地将代码保留在文档之外？

否。由GhostDoc生成的文档是样板文件（类似于在IDE中创建新的OO类如何使用构造函数或类似方法为类创建模板）。文档的有用部分是添加样板之后的内容。

尽管您必须记录工作场所中的所有内容，但您的同事似乎找到了解决问题的完美方法：假装。

在静态类型的语言中，Javadoc样式的文档不是针对作者的，而是针对使用者的。自动生成只是使作者更容易维护供其他人使用的文档。

如果您使用的是静态类型的语言，而没有编写供第三方使用的库，那么自动生成并不会给您带来太多好处，根据我的经验，这种用法很少使用。如果您使用的是动态类型的语言，则通常使用javadoc样式的文档来记录类型，即使是仅供内部使用，但自动生成不知道类型，因此，它为您节省的一切都避免了手动复制样板。

无论哪种方式，都不要将自动发电视为生产成品。可以将其视为为您制作样板，因此，手动进行的任何更改都是重要的。

自动生成代码文档是否有逻辑上的原因？

从谁的角度看？

如果我经营的是公司或开发团队，那么没有充分的理由。我坚定地在“评论中应解释为什么 ”扎营。强迫人们注释类/函数/属性要比一文不值的糟糕，因为他们过时，误导读者，被用作无法编写可读代码的借口，等等。这些注释会浪费时间来编写它们，阅读代码以及由它们引起的错误。有人会说JavaDoc风格的API文档是进行注释的原因，但是即使在该论点下，您的代码中的一小部分也应该是公共API的一部分，并且JavaDoc不能替代实际的API文档。

尽管有我的意见，但作为开发人员，我曾在一些地方要求在这些地方发表评论。由于我没有时间或耐心来写一堆没人会用的废话，所以我改用GhostDoc。这使我可以把时间花在实际做重要的事情上。比更改公司政策更有效率。

使用GhostDoc发现的另一件好事是，它可以检查我的名字是否好。如果GhostDoc无法为功能生成体面的文档，那是我的功能或参数名称可能很差的味道。虽然我不使用的工具只是这个，这是一个可爱的小的副作用，如果我被做反正浪费我的时间。

编辑：我误解了原来的问题；尽管我认为生成文档（即非代码文档）可能非常有价值（请参阅下面有关Doxygen的原始答案），但是自动生成注释（这是GhostDoc的实际做法）对我来说听起来很疯狂。我不明白为什么有人会期望程序能够读取未注释的源代码并编写能够真正澄清它的注释。

可以想到的是我，一个非常“聪明”的评论代工具可以进行编程，以识别特定的模式，并产生“如何”式的评论; 例如，它可以识别Knuth的方差计算算法，并提供注释以说明其工作方式以及为何天真的算法不合适。也许甚至可以对这种实用程序进行编程，以识别规范的面向对象的设计模式（例如Abstract Factory）并插入注释，以指示正在使用的模式以及哪些类在发挥什么作用。

但在我看来，最有用的评论不解释的东西“怎么样”的作品，因为代码本身应该表现出这一点，但“ 为什么 ”的评论，解释“为什么”一个特别的事情正在做。正如David Hammen在下面的注释中指出的那样，为了生成“为什么”注释，实用程序需要“阅读程序员的思想”。显然这是不可能的。

但是，基于给出的示例，看来GhostDoc甚至没有完成创建真正的“方式”样式注释的任务。所以，在我看来，有害无益，因为它不会产生可空洞的和误导性的（如在第二个例子）。

原始答案：为什么自动提取和格式化文档是个好主意

我的软件团队使用Doxygen。这样做的主要原因是我们需要代码功能/行为/等方面的非源代码（即非程序员可读）文档，但是我们认为将其集成到源代码本身是比将其集成到源代码中更好的做法。保留它作为第二个文件。这有助于我们使文档与源代码保持同步（尽管当然不能完全保证，自动化程度要低得多），并最大程度地减少了编写文档的开销（因为可以将一段代码的文档轻松地合并到源代码中）。包含代码本身的文件）。

因此，我们Doxygen的使用重点不是从代码本身中提取信息，而是使源代码的文档尽可能与源代码本身尽可能接近。

这也使我们可以使用一个工具来创建描述整个代码库的“操作理论”和描述软件产品的几套“发行说明”，但实际上它们中不包含任何实际的“代码文档”。典型的意义。

至于为什么我们需要有关代码行为的非源代码文档，有两个原因：

• 我们的产品不仅仅是软件。这是一个复杂的工具，它集成了许多硬件组件，包括一些高档激光和射流技术。我们需要没有太多软件背景的工程师对代码内部的确切行为有一个很好的了解，并且告诉他们“阅读源代码”将无法实现这一目标。
• 我们必须遵循许多质量法规，其中一些是公司内部强制执行的，而其他则是联邦政府法律强制执行的。尽管质量过程（或至少可以）非常有价值和有用，但它涉及不可忽略的间接费用，软件团队有责任提供这种详细的软件文档。同样，将此文档与代码本身集成在一起可以最大程度地减少开销，并有助于我们使文档保持最新。

请注意，第二个要点与其他一些答案很相似，即管理人员希望知道每个源代码都存在一些文档（无论质量如何），从而放心（/吹牛的权利）。但是，这种框架化方法忽略了以下事实：外部授权的文档实际上可以具有某些合法的优势。

当然，自动化文档在可以复制由代码作者编写的有见地，适当的描述时特别有用。否则，它只是一个荣耀的自动格式化程序。

但是格式化并不是没有用的。能够一目了然地找到，分类并保证完整的大型组件的公共方法是有价值的。如果您需要一个转换frobnick器，而该转换器不存在，那么您不经过源代码就可以知道它不存在。（负面结果也很有价值：您知道您必须做某事，并且有更多时间这样做，因为您不必涉水。）

因此，是的，自动生成文档会增加一些价值。当然，管理者可能不会想像的那么多，而且通常还不如真正好的复制编辑器所想的那么多，但也不是没有。

以这种形式，它比没用更糟，但仅是因为它仅依赖于公共签名（对于Javadoc，对于任何阅读该API文档的人都是可见的）。

但是可以编写也考虑该方法主体的自动化文档工具。作为概念证明，我编写了一个a脚的Eclipse小插件，其中添加了从文档化方法调用到Javadoc的其他方法列表。（当然，并非每次调用都可以按包定义过滤器。）

实际上，当我在脑海中绘制出一个完全陌生的代码库时，我发现它非常方便。当然，这是一个非常有限的用例，但这绝对是一个帮助。

根据经验，问题的答案是：是的，但是我们需要更智能的工具。

更新：当然，还有一个问题（写任何类型的文档之前应该问一个问题）是目标受众是谁。如果我们正在为该API的客户编写公共API的文档，那么添加所有这些实现细节是一个很大的禁忌，因为您在Javadoc中放入的任何内容在技术上都是该API的一部分。

但是，如果目标受众是使用同一产品的其他开发人员，则可以自动添加有关实现细节的信息，例如哪些方法可以修改或读取特定字段，这既可以接受，也非常有用。

我不了解其他环境，但是当涉及到其他人编写的大型（通常是开源）PHP项目时，phpXRef绝对可以节省生命（特别是如果该文档在线放置并且Google可以对其进行索引）。

即使是一个评论不佳的项目，也至少可以帮助我追踪在何处定义了事物以及在何处使用了事物（例如，在重构时）。

如果评论得当，结果页面将形成接近于代码库的完美圣经（无论如何供我使用）。

此外，我偏爱的IDE将自动生成注释块（如果我键入/ **），这大约为我完成了75％的注释工作。令人惊讶的是，由于我不得不向其他人（以及将来的我）解释我在做什么，我在编码器的整个生命周期中都停止犯下多少愚蠢的事情。当我对doc生成器的评论大于该方法时，这通常意味着我没有足够的咖啡，并且可能想加倍努力。

这些相同的注释块还创建了内联补全“帮助”文本，因此在编写函数调用时，我可以确切地看到（其他编码者）期望的内容。对我来说，这极大地提高了生产力（尤其是在一些极少数情况下，其他有用的开发人员写了“为了好吧，请不要做X”），这可以节省很多痛苦。

我不能足够强调在复杂的（通常是错误命名的）PHP项目中指定预期的输入类型以及在不常用的方法中指定参数顺序的用处。即使使用自己的代码，我也永远无法记住我为某个时代未曾接触过的东西指定的参数。

在一个实例中，这意味着反复出现问题的根源是，由于某种原因，它严重反映了以前的开发人员，因此在很多地方都定义了一些函数甚至常量（对于添加的“乐趣”存在一定程度的不一致） 。那是离开该项目的标志。

在我加入之前开始的大型项目中，我可以看到哪个开发人员（假设他们使用名称和电子邮件标记了班级文件），并且能够找到合适的开发人员并与之交谈非常有用。

自动任务列表-使用@todo标记（在我发现自己从事的项目中很常见）意味着文档可以跟踪需要更多工作（或被认为缺少的功能）的内容。同样，我的IDE会对此进行跟踪，仅此一项就可以成为您首先需要注意的内容的良好指南。

最后（对我来说非常重要）消除了将所有内容写出来，然后在一些（读很多）编码人员提交更改且不与文档维护人员交谈时保持最新状态的不平凡的开销。

因此，原因包括：

• 为以后的开发人员节省了大量时间，
• 跟踪调用（定义）函数的位置，
• 发现愚蠢的编码，
• 发现（如另一个人所指出的）明显缺少的东西，
• 简化重构（从不有趣）
• （在许多情况下）了解开发人员正在尝试做什么（假设他或她留下了一些笔记）。
• 如果该项目足够复杂，可以进行多个许可证（不好玩），那么我可以快速查看哪些许可证适用于任何给定的部分。诚然，这是附带的好处。
• 了解与谁讨论项目文件的想法。
• 自动任务清单

同样，不要低估使尖头的老板保持高兴的价值。

简而言之，“自动文档注释”对我的编码习惯至关重要。我相信有很多人认为这很that脚，但我也肯定有很少一部分人确切地知道我在说什么。在发现phpXRef（和我最喜欢的IDE）之前，我不知道如何生存。

通常最好使用文档生成器来创建样板或“替代”注释，然后由实际开发人员进行修改。我经常使用Eclipse的auto-JavaDoc函数来生成带有参数类型的标头注释，并返回已经填充的值，然后只需添加文档的“肉”即可。

作为C＃开发人员，我使用Stylecop，它要求对所有类，方法等进行注释。我使用工具自动生成这些注释。在大多数情况下，该工具生成的注释就足够了，并且可以通过对象的名称来推断，例如Person类具有和ID字段。

但是，如果我想进一步评论一个不明显的方法，可以很容易地扩展样板文档以及有关其功能的一些解释。例如：我的Person类上有一个方法，该方法返回FirstName + Lastname，但是我添加了一些关于缺少两者的情况的记录。

简而言之：如果您从不更改生成器提供的文本，我认为样板文档可能是有害的。在这种情况下，只是线路噪声。但是，如果您将它们视为模板，它们就会降低为您自己或您的消费者提供良好而有用的评论的门槛。您可以在不自动生成评论的情况下写评论吗？当然可以，但是您必须遵守这种格式（在C＃情况下，手工生成非常冗长和烦人），并且降低了您真正提供此注释的机会。

避免重言式

您唯一需要任何类型的代码文档都是为了解释为什么方法/函数正在执行某项操作，因此名称应足以说明其正在执行的操作。

如果您执行的操作不是惯用语言，或者违反了最少惊讶的原则，则需要文档。

代码的使用者几乎需要自动生成的文档，而该文档只是信息输出的格式化程序。Javadoc做到了这一点。

并非每件事都要手动记录

诸如getXXX / setXXX方法之类的事情应该是不言自明的，因此，可以让您自动知道它们存在的自动生成文档将受到欢迎。

至少是“自动”类型的代码文档，对于尝试理解应用程序的人们来说，是最不常用的标准。

最老练的用户不会喜欢自动代码文档。他们宁愿拥有“目标明确”的文档来告诉他们需要（一点）告诉他们什么。

最不熟练的用户不会因为相反的原因而欣赏它。他们还是不明白。

自动代码文档的“最欣赏”用户是那些“有点知识”是一件危险的事情。”他们可能会或可能不会理解文档（尽管他们可能会），但他们会对“成为保持循环。”此受众包括大多数“管理”类型。如果那是您的主要受众，那么自动代码文档可能是一件好事。

通过显示MSDN可以简单地回答“为什么生成文档”的简单答案。

想象一下，试图编写一个使用任何没有API文档的库的程序。这将是一场噩梦。MSDN是可以从源代码和注释生成的文档类型的一个很好的例子，并为开发人员提供了必不可少的资源。

如果您正在编写一个应用程序（即不是供他人使用的库），那么也许有一种情况值得您注意：但是即使如此，大型的，仅限内部使用的应用程序中也不包含大量的库无论如何？当您加入这样的团队时，拥有一些可浏览的API文档将对您有所帮助。

没有工具会为您编写文档，但是它们确实为您提供了必须手动编写的样板，某些工具（例如doxygen）还将生成图表和参考列表（例如，被调用和被调用的函数） ），即使通过查看源代码也很难发现。

显然，应将务实的常识应用于所记录的内容，可以忽略属性和次要功能（甚至在工具中也可以从生成中跳过这些知识），但是任何时候任何时候都不应说“有源代码，这足以说明文档” 。