我正在检查我刚刚编写的一些新代码，并将 NDoc sytle 注释添加到我的类和方法中。我希望生成一个非常好的 MSDN 风格文档以供参考。
一般来说，为类和方法编写注释时有哪些好的指导原则？ NDoc 评论应该说什么？他们不应该说什么？
我发现自己正在查看 .NET 框架注释的内容，但这很快就过时了；如果我能有一些好的规则来指导自己，我可以更快地完成我的文档。
I'm going through some new code I just wrote and adding NDoc sytle comments to my classes and methods. I'm hoping to generate a pretty good MSDN style document for reference.
In general, what are some good guidelines when writing comments for a class and for a method? What should the NDoc comments say? What should they not say?
I find myself looking at what the .NET framework comments say, but that gets old fast; if I could have some good rules to guide myself, I could finish my docs a lot faster.
发布评论
评论（8）
在用于构建 API 文档的注释中，您应该：
解释该方法或属性的作用、它存在的原因，并解释对代码的普通使用者来说不言自明的任何领域概念。
列出您的参数的所有前提条件（不能为空，必须在某个范围内等）
列出该方法可能抛出的任何异常（以及在什么情况下）。
如果存在类似的方法，请解释它们之间的差异。
引起对任何意外情况的注意（例如修改全局状态）。
枚举任何副作用（如果有）。
In comments used to build API documentation, you should:
Explain what the method or property does, why it exists at all, and explain any domain concepts that are not self-evident to the average consumer of your code.
List all preconditions for your parameters (cannot be null, must be within a certain range, etc.)
List any postconditions that could influence how callers deal with return values.
List any exceptions the method may throw (and under what circumstances).
If similar methods exist, explain the differences between them.
Call attention to anything unexpected (such as modifying global state).
Enumerate any side-effects, if there are any.
如果您最终得到的评论没有任何价值，那么它们就是浪费。
例如
......您绝对没有添加任何价值，只是添加了更多代码来维护。
代码中常常充斥着这些多余的注释。
If you end up with comments that don't add any value, they're just wasteful.
For example
...you added absolutely no value and just added more code to maintain.
Too often code is littered with these superfluous comments.
StyleCop 提供代码和注释风格的提示。它给出的建议符合MSDN文档风格。
至于注释的内容，它应该为代码的用户提供足够的信息，让他们了解预期的行为。它还应该回答用户可能存在的潜在问题。因此，请尝试以对代码一无所知的人的身份使用您的代码，或者更好的是，请其他人这样做。
StyleCop provides hints for code and commenting style. The suggestions it gives are in line with the MSDN documentation style.
As for the contents of the comment, it should give the user of your code enough information on what kind of behavior to expect. It should also answer potential questions the user might have. So try to use your code as someone who doesn't know anything about the code, or even better, ask someone else to do so.
不要忘记什么是有效的 XML。例如：（
错误：无效的 XML）。
Don't forget what's a valid XML is. For example:
(Error: invalid XML).
对于属性，您的注释应指明该属性是只读、只写还是读写。如果您查看所有官方 MS 文档，属性文档注释总是以“获取...”、“获取或设置...”以及（非常罕见，通常避免只写属性）“设置...”开头
For properties, your comment should indicate whether the property is read only, write only or read write. If you look at all official MS documentation, property doc comments always start with "Gets ...", "Gets or sets..." and (very rarely, avoid write only properties usually) "Sets ..."
我写了<摘要>评论以包含我想知道我是否是调用该函数（或实例化该类）的人的信息。
我写下<备注>评论以包含我想知道我是否负责调试或增强该函数或类的信息。注意：这并不能取代良好的内联注释的需要。但有时对函数/类的内部工作原理的总体概述非常有帮助。
I write the <summary> comment to include the information I would want to know if I was the one calling that function (or instantiating that class).
I write the <remarks> comment to include information I would want to know if I was tasked with debugging or enhancing that function or class. Note: this doesn't replace the need for good inline comments. But sometimes a general overview of the inner workings of the function/class are very helpful.
正如 MSDN 页面中所述，您可以使用 XML 文档注释来生成自动更新文档，因此如果您正在编写 API 并且不想在代码和文档上进行两次工作，那么它是有意义的，并且保持它们同步的额外好处 - 每次更改代码时，您都会修改适当的注释并重新生成文档。
使用
/doc进行编译，编译器将搜索源代码中的所有 XML 标签并创建 XML 文档文件，然后使用诸如 Sandcastle 生成完整的文档。As stated on the MSDN page, you use XML documentation comments to generate documentation automatically, so it makers sense if you're writing an API and don't want to work twice at both code and documentation, with the added benefit of keeping them in sync - every time you change the code, you modify the appropriate comments and regenerate the docs.
Compile with
/docand the compiler will search for all XML tags in the source code and create an XML documentation file, then use a tool such as Sandcastle to generate the full docs.关于评论的一件事是更新它们。太多人更改了功能，然后没有更改注释来反映更改。
One thing about comments is UPDATING them. Too many people alter a function then don't change the comment to reflect the change.