记录您的 .Net 代码的最佳方法是什么？ [关闭]

Question

您和我都知道为代码创建文档真的很无聊，我将其作为讨论来分享您为代码创建文档的经验。

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

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

2.提供源文档的方法和规则

3.其他开发者代码注释对你有用吗

Answer 1

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

这是我的看法：

---

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

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

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

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

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