XML注释：使用或不使用？

StackOverflow https://stackoverflow.com/questions/457936

  •  19-08-2019
  •  | 
  •  

题

我的同事很少（如果有的话）对我们的软件工作时使用XML评论（我不能说我没有更好）。我最近看到使用它们的好处，但他们真的值得的，如果他们记录的代码写清楚（表现/描述性的变量/函数名，一些在线评论）？

谢谢！

有帮助吗？

解决方案

XML注释是有用的，用于生成文档。如果代码写清楚，那么你不应该需要评论来帮助你理解代码。

然而文档注释是有用的类别的用户，因为它（应该）包含（一个或多个）的类或方法的功能的描述，而不是代码的描述。

其他提示

我觉得代码注释是非常重要的，尤其是在面向公众的方法和属性。人们可能是好意时，他们说他们的代码是描述性的，也许是这样，但想到新来的家伙谁看这个的：

Linker.Extract(IpoValidator validator, MeanDexIndicator Indicator)

除非他理解他可能不知道它的目的的方法的上下文中。主要的问题的人似乎有意见是，他们都不是很有益的。这是因为人写差评。你可以讲述发生了什么事情它不是什么。我可以看到，方法是一种提取方法，所以这样的评论：

 <Summary>Extracts The Fumble <\Summary>

是能量的浪费。以下是更好的：

 <Summary>
 The Fumble needs to be extracted before the bopper can be used. In order for 
 extraction to work a validator and indicator need to be provided. Once extracted 
 the bopper is available in the property Linker.Bopper. On fail this 
 method will raise the CrappedOutException.
 </Summary>

请参阅区别？

我倾向于使用仅摘要PARAMS和回报，因为他们都展现在智能感知，一切就像言论，可能是在浪费时间，因为他们并不总是显示。

至于是谁拒绝改变的东西后，更新他的意见的人。代码审查应该抓住这一点。我个人使用的私有方法XML注释和道具两个，而是一个是个人的选择。在面向公众的方法和属性？我是非可选的。

XML注释是对API的真正有用的，甚至没有在一小群使用。

我们发现它是有用的，因为VS自动检查，以确保某些意见的存在。此外，新的人进入该组织已经使用VS之前知道如何评论工作，我们没有解释代码注释的一个新的系统。有时我们从它生成的文档，但实际上它只是更容易，因为它在许多事情为您填充我们使用它（像一些参数标签等）

至于面向内部的代码和注释，这里的交通过杰弗里巴勒莫的，我只是理解并具有一致。

在概要：很多评论只是降低了可读性和帮助不大，很好的意见是非常有用的，但增加维护软件的成本，甚至可能导致重大问题时，他们没有维护和提供虚假信息。有没有替代的精心设计和代号。

时不存在在功能忽略，但通过一些XSLT可以被处理的注释标签直接变成文档？评论都不错（我使用它们），但我认为它可以做注释标记的值和直接转化大于用作文档注释的。因此，在总结，使用注释标签被他人阅读文档，使用笔记注释你的自我或“幕后”的东西（即“OMG解决这个问题的世界爆炸之前！”）

许可以下： CC-BY-SA 和 归因
不隶属于 StackOverflow
scroll top