XML 注释非常适合 API 开发。 它们与 Intellisens 配合得很好，可以让您立即生成 HTML 帮助文档。
但这不是免费的：维护它们会很困难（看看任何重要的例子，你就会明白我的意思），所以它们往往会很快过时。 因此，审查 XML 注释应作为强制检查添加到代码审查中，并且每次更新文件时都应执行此检查。
好吧，因为维护起来很昂贵，因为很多非私有符号（在非 API 开发中）仅由 1 或 2 个类使用，并且因为这些符号通常是不言自明的，所以我永远不会强制执行这样的规则：每个非私有符号都应该用 XML 注释。 这会造成杀伤力过大且适得其反。 您将得到的是我在很多地方看到的：几乎空的 XML 注释，没有向符号名称添加任何内容。 而且代码的可读性稍差......
我认为关于正常（非 API）代码中的注释的非常非常重要指南不应该是关于它们应该如何写的但关于它们应该包含什么。 许多开发人员仍然不知道要写什么。 对应该注释的内容的描述（带有示例）比简单的“在每个非私有符号上使用 XML 注释”更适合您的代码。
Comments are very often outdated. This always has been a problem. My rule of thumb : the more you need to work to update a comment, the faster that comment will be obsolete.
XML Comments are great for API development. They works pretty well with Intellisens and they can have you generate an HTML help document in no time.
But this is not free: maintaining them will be hard (look at any non-trivial example, you will understand what I mean), so they will tend to be outdated very fast. As a result, reviewing XML Comments should be added to your code review as a mandatory check and this check should be performed every time a file is updated.
Well, since it is expensive to maintain, since a lot of non private symbols (in non-API development) are used only by 1 or 2 classes, and since these symboles are often self-explanatory, I would never enforce a rule saying that every non-private symbol should be XML commented. This would be overkill and conterproductive. What you will get is what I saw at a lot of places : nearly empty XML Comments adding nothing to the symbole name. And code that is just a little less readable...
I think that the very, very important guide line about comments in normal (non-API) code should not be about HOW they should be written but about WHAT they should contain. A lot of developers still don't know what to write. A description of what should be commented, with examples, would do better for your code than just a plain : "Do use XML Comments on every non-private symbole.".
一般来说，我会努力向所有公共/受保护成员添加有意义的注释，这很方便，因为如果您在构建期间打开 xml 注释，您会收到缺少注释的自动警告。 根据复杂性，我可能不会填写每个细节 - 即，如果每个参数必须做什么都是100％明显的（即没有特殊逻辑，并且只有一种逻辑解释方式）变量），那么我可能会变得懒惰，不添加有关参数的注释。
但我当然会尝试描述方法、类型、属性等代表/做什么。
I very rarely comment on method variables, and equally rarely fields (since they are usually covered by a property, or simply don't exist if using auto-implemented properties).
Generally I try hard to add meaningful comments to all public/protected members, which is handy, since if you turn on the xml comments during build, you get automatic warnings for missing comments. Depending on the complexity, I might not fill out every detail - i.e. if it is 100% obvious what every parameter has to do (i.e. there is no special logic, and there is only 1 logical way of interpreting the variables), then I might get lazy and not add comments about the parameters.
But I certainly try to describe what methods, types, properties, etc represent/do.
We document the public methods/properties/etc on our libraries. As part of the build process we use NDoc to create an MSDN-like web reference. It's been very helpful for quick reference and lookup.
It's also great for Intellisense, especially with new team members or, like you said, when the original author is gone.
I agree that code, in general, should be self-explanatory. The XML documention, to me, is more about reference and lookup when you don't have the source open.
Personally my opinion is to avoid commenting. Commenting is dangerous. Because in industry we always update code(because business & requirements are always changing), but vary rarely we update our comments. This may misguide the programmers.
Personally, we make sure that every public and protected method has XML comments. It also will provide you with Intellisense, and not just end-user help documentation. In the past, we also have included it on privately scoped declarations, but do not feel it is 100% required, as long as the methods are short and on-point.
Don't forget that there are tools to make you XML commenting tasks easier:
GhostDoc - Comment inheritance and templating add-in.
Sandcastle Help File Builder - Edits the Sandcastle projects via a GUI, can be run from a command line (for build automation), and can edit MAML for help topics not derived from code. (The 1.8.0.0 alpha version is very stable and very improved. Have been using it for about a month now, over 1.7.0.0)
发布评论
评论（6）
评论往往已经过时。 这一直是个问题。 我的经验法则：更新评论所需的工作越多，该评论就会过时得越快。
XML 注释非常适合 API 开发。 它们与 Intellisens 配合得很好，可以让您立即生成 HTML 帮助文档。
但这不是免费的：维护它们会很困难（看看任何重要的例子，你就会明白我的意思），所以它们往往会很快过时。 因此，审查 XML 注释应作为强制检查添加到代码审查中，并且每次更新文件时都应执行此检查。
好吧，因为维护起来很昂贵，因为很多非私有符号（在非 API 开发中）仅由 1 或 2 个类使用，并且因为这些符号通常是不言自明的，所以我永远不会强制执行这样的规则：每个非私有符号都应该用 XML 注释。 这会造成杀伤力过大且适得其反。 您将得到的是我在很多地方看到的：几乎空的 XML 注释，没有向符号名称添加任何内容。 而且代码的可读性稍差......
我认为关于正常（非 API）代码中的注释的非常非常重要指南不应该是关于它们应该如何写的但关于它们应该包含什么。 许多开发人员仍然不知道要写什么。 对应该注释的内容的描述（带有示例）比简单的“在每个非私有符号上使用 XML 注释”更适合您的代码。
Comments are very often outdated. This always has been a problem. My rule of thumb : the more you need to work to update a comment, the faster that comment will be obsolete.
XML Comments are great for API development. They works pretty well with Intellisens and they can have you generate an HTML help document in no time.
But this is not free: maintaining them will be hard (look at any non-trivial example, you will understand what I mean), so they will tend to be outdated very fast. As a result, reviewing XML Comments should be added to your code review as a mandatory check and this check should be performed every time a file is updated.
Well, since it is expensive to maintain, since a lot of non private symbols (in non-API development) are used only by 1 or 2 classes, and since these symboles are often self-explanatory, I would never enforce a rule saying that every non-private symbol should be XML commented. This would be overkill and conterproductive. What you will get is what I saw at a lot of places : nearly empty XML Comments adding nothing to the symbole name. And code that is just a little less readable...
I think that the very, very important guide line about comments in normal (non-API) code should not be about HOW they should be written but about WHAT they should contain. A lot of developers still don't know what to write. A description of what should be commented, with examples, would do better for your code than just a plain : "Do use XML Comments on every non-private symbole.".
我记录公共类和这些类的公共/受保护成员。
我不记录私有或内部成员或内部类。 因此变量（我认为你的意思是字段）因为它们是私有的。
目的是为无法访问源代码的开发人员创建一些文档。
尽量举一些用法不明显的例子。
I document public classes and the Public/Protected Members of those classes.
I don't document private or internal members or internal classes. Hence variables (I think you mean fields) because they are private.
The objective is to create some documentation for a developer who does not have ready access to the source code.
Endeavour to place some examples where usage is not obvious.
我很少评论方法变量，同样很少评论字段（因为它们通常被属性覆盖，或者如果使用自动实现的属性则根本不存在）。
一般来说，我会努力向所有公共/受保护成员添加有意义的注释，这很方便，因为如果您在构建期间打开 xml 注释，您会收到缺少注释的自动警告。 根据复杂性，我可能不会填写每个细节 - 即，如果每个参数必须做什么都是100％明显的（即没有特殊逻辑，并且只有一种逻辑解释方式）变量），那么我可能会变得懒惰，不添加有关参数的注释。
但我当然会尝试描述方法、类型、属性等代表/做什么。
I very rarely comment on method variables, and equally rarely fields (since they are usually covered by a property, or simply don't exist if using auto-implemented properties).
Generally I try hard to add meaningful comments to all public/protected members, which is handy, since if you turn on the xml comments during build, you get automatic warnings for missing comments. Depending on the complexity, I might not fill out every detail - i.e. if it is 100% obvious what every parameter has to do (i.e. there is no special logic, and there is only 1 logical way of interpreting the variables), then I might get lazy and not add comments about the parameters.
But I certainly try to describe what methods, types, properties, etc represent/do.
我们在我们的库中记录了公共方法/属性/等。 作为构建过程的一部分，我们使用 NDoc 创建类似 MSDN 的 Web 参考。 这对于快速参考和查找非常有帮助。
这对于 Intellisense 来说也很棒，特别是对于新的团队成员，或者就像你说的，当原作者去世时。
我同意，一般来说，代码应该是不言自明的。 对我来说，XML 文档更多的是当您没有打开源代码时的参考和查找。
We document the public methods/properties/etc on our libraries. As part of the build process we use NDoc to create an MSDN-like web reference. It's been very helpful for quick reference and lookup.
It's also great for Intellisense, especially with new team members or, like you said, when the original author is gone.
I agree that code, in general, should be self-explanatory. The XML documention, to me, is more about reference and lookup when you don't have the source open.
我个人的意见是避免发表评论。 评论是危险的。 因为在行业中我们总是更新代码（因为业务和需求总是在变化），但我们很少更新我们的评论。 这可能会误导程序员。
Personally my opinion is to avoid commenting. Commenting is dangerous. Because in industry we always update code(because business & requirements are always changing), but vary rarely we update our comments. This may misguide the programmers.
就个人而言，我们确保每个公共和受保护的方法都有 XML 注释。 它还将为您提供智能感知，而不仅仅是最终用户帮助文档。 过去，我们也将其包含在私有作用域声明中，但并不认为这是 100% 必需的，只要方法简短且切题即可。
不要忘记有一些工具可以让您更轻松地完成 XML 注释任务：
Personally, we make sure that every public and protected method has XML comments. It also will provide you with Intellisense, and not just end-user help documentation. In the past, we also have included it on privately scoped declarations, but do not feel it is 100% required, as long as the methods are short and on-point.
Don't forget that there are tools to make you XML commenting tasks easier: