记录.Net代码的最佳方法是什么？

Question

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

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

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

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

3.其他开发人员代码评论是否帮助您了解了有用的内容

Answer 1

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

以下是我的看法：

---

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

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

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

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

3）Abso-freaking-lutely。阅读我自己的代码通常很简单，但每个开发人员的工作方式都不同。当你有其他人写的代码时，评论可以区分理解与否。