重复的XML注释 - 重点是什么？ [英] Repetitive XML comments -- what's the point?

问题描述

我经常看到这样的代码：


///< summary>

///删除一个节点。

///< / summary>

///< param name =" node">要删除的节点。< / param>

public void RemoveNode（节点节点）{

< ...>

}


在我看来，有这样做没有任何好处。它没有给

表带来任何影响，并产生以下问题：


o它妨碍了代码 - 这是不必要的噪音。


o当某些重大变化时，代码和评论

都需要更新，而不仅仅是代码。


o它经常会产生不良代码（不要担心给这种方法更好的名字 - 评论解释得很好）。


我见过一些知识渊博的人写这样的代码，请注意。

为什么人们会这样做？这只是一致性吗？是否必须对每一个

方法进行评论？

I often see code like this:

/// <summary>
/// Removes a node.
/// </summary>
/// <param name="node">The node to remove.</param>
public void RemoveNode(Node node) {
<...>
}

In my view, there is no benefit in doing this. It brings nothing to the
table, and creates the following issues:

o It get in the way of the code -- it''s unnecessary noise.

o When something significant changes, both the code and the comment
need to be updated, rather than just the code.

o It often breeds bad code ("don''t worry about giving that method a
better name -- the comment explains it well").

I''ve seen some pretty knowledgeable people write code like this, mind you.
Why do people do it? Is it just a consistency thing? Must every single
method be commented?

推荐答案

2006年6月10日消息< 11 *** *************@tjb.invalid.invalidtjb写道：

On 06/10/2006 in message <11****************@tjb.invalid.invalidtjb wrote:

>我见过一些知识渊博的人写代码这样，请注意。
为什么人们会这样做？这只是一致性吗？必须评论每一个方法吗？

>I''ve seen some pretty knowledgeable people write code like this, mind you.
Why do people do it? Is it just a consistency thing? Must every single
method be commented?

没有要求评论代码。然而，在一个有许多程序员的组织中，有些人会不时转换工作，我会认为内部标准会使它成为一个必要条件。 />
维护目的。


-

Jeff Gaines

There''s no requirement to comment code. However, in an organisation with
many programmers, some of whom will switch jobs from time to time, I would
have thought internal standards would make it a requirement for
maintenance purposes.

--
Jeff Gaines

// /< summary>

/// <summary>

///删除节点。

///< / summary>

/// < param name =" node">要删除的节点。< / param>

public void RemoveNode（Node node）{

< ... >

}

/// Removes a node.
/// </summary>
/// <param name="node">The node to remove.</param>
public void RemoveNode(Node node) {
<...>
}

XML注释带来许多好处。第一个是显而易见的，适用于

所有类型的评论 - 功能说明。我同意XML格式对人类来说不是最好的。


但XML注释会给你以下内容：

1。 VS可以从这些评论中自动生成IntelliSense快速信息和对象

浏览器描述。

2.使用专业工具（例如我们的VSdocman），您可以生成

代码中类似MSDN的文档，只需几秒钟。这就是Microsoft

和大型组件供应商的做法。


添加此类评论非常简单，只需按/三次即可。如果您使用

评论工具，更新也很容易。


因此，如果您计划分发代码或与团队共享代码，那么

至少评论其他人使用的公共成员是个好主意。这样

其他人可以得到他们的快速帮助。

-

Peter Macej

Helixoft - < a rel =nofollowhref =http://www.helixoft.comtarget =_ blank> http://www.helixoft.com

VSdocman - 评论者和C＃，VB的类文档生成器

..NET和ASP .NET代码

XML comments bring many benefits. The first is obvious and applies to
all types of comments - function explanation. I agree that XML format is
not the best for humans.

But XML comments give you the following:
1. VS can automatically generate IntelliSense quick info and Object
browser descriptions from these comments.
2. Using specialized tools (e.g. our VSdocman), you can generate
MSDN-like documentation from your code in seconds. This is how Microsoft
and big component vendors do it.

Adding such comment is very easy, just press / three times. If you use
commenting tools, updating is also very easy.

So if you plan to distribute your code or share it with the team, it is
good idea to comment at least public members used by others. This way
other people can get quick help for them.
--
Peter Macej
Helixoft - http://www.helixoft.com
VSdocman - Commenter and generator of class documentation for C#, VB
..NET and ASP .NET code

Jeff Gaines< wh ****** ***@newsgroups.nospamwrote：

Jeff Gaines <wh*********@newsgroups.nospamwrote:

06/10/2006 in message< 11 *************** *@tjb.invalid.invalidtjb写道：

On 06/10/2006 in message <11****************@tjb.invalid.invalidtjb wrote:

>>我见过一些知识渊博的人写这样的代码，请注意。
为什么人们这样做？这只是一致性吗？必须评论每一个方法吗？

>>I''ve seen some pretty knowledgeable people write code like this, mind you.
Why do people do it? Is it just a consistency thing? Must every single
method be commented?

没有要求评论代码。然而，在一个有许多程序员的组织中，有些人会不时转换工作，我会认为内部标准会使它成为一个必要条件。 />
维护目的。

There''s no requirement to comment code. However, in an organisation with
many programmers, some of whom will switch jobs from time to time, I would
have thought internal standards would make it a requirement for
maintenance purposes.

我不反对评论代码 - 我反对*重复*

评论，就像在示例中一样发布：


///< summary>

///删除节点。

///< /摘要>

///< param name =" node">要删除的节点。< / param>

public void RemoveNode（Node node）{

< ...>

}


如何改善以下内容？


public void RemoveNode（Node node）{

< ...>

}


我看到知识渊博的开发人员一直在编写像前者一样的代码。

但为什么呢？与后者相比，它没有明显的好处 - 但它有明显的缺点。

I''m not arguing against commenting code -- I''m arguing against *repetitive*
comments, like in the example posted:

/// <summary>
/// Removes a node.
/// </summary>
/// <param name="node">The node to remove.</param>
public void RemoveNode(Node node) {
<...>
}

How does this improve over the following?

public void RemoveNode(Node node) {
<...>
}

I see knowledgeable developers write code like the former all the time.
But why? Compared to the latter, it has no clear benefit -- and yet it has
clear drawbacks.

这篇关于重复的XML注释 - 重点是什么？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！