c# - 记录您的 .Net 代码的最佳方法是什么？

Question

你和我都知道为代码创建文档真的很无聊，我将它作为一个讨论打开，你分享你为代码创建文档的经验。

我认为项目文档不同于项目文档中的代码文档，您可以使用 UML 来描述整个项目、算法、设计、架构。但是，在您开发 DLL 库或提供 Web 服务或任何其他工具时，您的代码文档非常有效其他开发人员将使用的代码。我认为讨论主题是：

1.您知道对生成文档有用的工具

score 1 · Accepted Answer

这是社区通常倾向于不同意的事情之一。不是一般...我认为我们都承认代码文档是一件好事™，但我们如何做到这一点是个人问题。

这是我的看法：

我知道这很痛苦，但内联文档有助于让您保持专注，并为您提供一些您在回顾代码时可以参考的信息。

1) 我使用Sandcastle从我的库中生成帮助文件，我用 XML 文档注释记录这些文件。

2a) 始终为您的公共字段、属性和方法提供合理的 XML 文档。不要只是放/// <summary>FieldName</summary>，描述该领域的用途。

2b) 谨慎使用内联注释。不要注释每一行，而是注释代码块做一些有趣的事情或以有趣的方式，这样你（或其他任何人）可以在下次阅读代码时清楚地理解它。

3) Abso-freaking-lutely。阅读我自己的代码通常很简单，但每个开发人员的工作方式都不同。当你有一段别人写的代码时，注释可以决定理解与否。