Repetitive XML comments -- what's the point?

[tjb]

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?

[Jeff Gaines]

Re: Repetitive XML comments -- what's the point?

On 06/10/2006 in message <1110ts3fa9rrs$ .dlg@tjb.invali d.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.

--
Jeff Gaines

[Peter Macej]

Re: Repetitive XML comments -- what's the point?

/// <summary>

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

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

[tjb]

Re: Repetitive XML comments -- what's the point?

Jeff Gaines <whitedragon@ne wsgroups.nospam wrote:

On 06/10/2006 in message <1110ts3fa9rrs$ .dlg@tjb.invali d.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.

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.

[tjb]

Re: Repetitive XML comments -- what's the point?

Peter Macej <peter@helixoft .comwrote:

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

>
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.

My point is about repetitive comments, not XML comments.

[Peter Bromberg [C# MVP]]

Re: Repetitive XML comments -- what's the point?

The XML Comments "appear" repetitive because you are looking at them in the
code window. However, when they get translated into Intellisense or built
documentation such as a CHM Help file, they aren't repetitive at all.
Peter

--
Co-founder, Eggheadcafe.com developer portal:

http://www.eggheadcafe.com

UnBlog:

http://petesbloggerama.blogspot.com

"tjb" wrote:

Peter Macej <peter@helixoft .comwrote:
>

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

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.

>
My point is about repetitive comments, not XML comments.
>

[Mark Jerde]

Re: Repetitive XML comments -- what's the point?

The purpose is generating documentation.

"Creating a Chm build using Sandcastle"

https://blogs.msdn.com/sandcastle/archive/2006/07/29/682398.aspx

-- Mark

"tjb" <tjb@invalid.in validwrote in message
news:1110ts3fa9 rrs$.dlg@tjb.in valid.invalid.. .

>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?

[tjb]

Re: Repetitive XML comments -- what's the point?

"Peter Bromberg [C# MVP]" <pbromberg@yaho o.nospammin.com wrote:

The XML Comments "appear" repetitive because you are looking at them in the
code window. However, when they get translated into Intellisense or built
documentation such as a CHM Help file, they aren't repetitive at all.
Peter

But wherever you see the comment, you see the method/param name, right?
Thus, they're repetitive everywhere.

If I see "Removes a node." in intellisense, I also see "RemoveNode " (the
method name). The summary comment in intellisense tells me nothing more
than the method name does.

[Peter Macej]

Re: Repetitive XML comments -- what's the point?

My point is about repetitive comments, not XML comments.

If you omit <summarytag, you will have no method description in
IntelliSense. If you omit <paramtag, you will have description for
this parameter in Intellisense. The same applies for generated
documentation.

So while comment may seem long or redundant in source code, it is
necessary for proper generation of IntelliSense and documentation.


--
Peter Macej
Helixoft - http://www.helixoft.com
VSdocman - Commenter and generator of class documentation for C#, VB
..NET and ASP .NET code

[tjb]

Re: Repetitive XML comments -- what's the point?

Peter Macej <peter@helixoft .comwrote:

>My point is about repetitive comments, not XML comments.

>
If you omit <summarytag, you will have no method description in
IntelliSense. If you omit <paramtag, you will have description for
this parameter in Intellisense. The same applies for generated
documentation.
>
So while comment may seem long or redundant in source code, it is
necessary for proper generation of IntelliSense and documentation.

Again, though, what use is this intellisense documentation if (for all
intents and purposes) it already exists -- within the name of the method,
for example?

If I hover over a call to the method "CreateFroz zle" and intellisense pops
up and says, "Creates a frozzle.", I've gained nothing.

[tjb]

Re: Repetitive XML comments -- what's the point?

I wrote:

If I hover over a call to the method "CreateFroz zle" and intellisense pops
up and says, "Creates a frozzle.", I've gained nothing.

To be clear -- I'm not talking about situations where the developer
should've been more descriptive in the XML comment. I'm talking about
situations where it's not really possible to be any more descriptive --
situations where the name of the method (or whatever) documents itself.

[Ignacio Machin \( .NET/ C# MVP \)]

Re: Repetitive XML comments -- what's the point?

Hi,

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.

No really, you can just collapse it

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

No always, you should modify it ONLLY if the method task change or you
modify your parameters.
Now I do not remember if when you change parameters the comments changes
(don't think so)

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

Dont think so, is more likely the "no neeed to comment, it's
selfexplanatory "

[tjb]

Re: Repetitive XML comments -- what's the point?

"Ignacio Machin ( .NET/ C# MVP )" <machin TA laceupsolutions .comwrote:

>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.
>>

No really, you can just collapse it

Even so, there's still some text in the way. And it takes extra effort to
collapse it all -- they won't be collapsed by default in, say, VS 2005.

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

>
No always, you should modify it ONLLY if the method task change or you
modify your parameters.

It's still extra effort, however. :)

Now I do not remember if when you change parameters the comments changes
(don't think so)
>

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

>
Dont think so, is more likely the "no neeed to comment, it's
selfexplanatory "

But why comment at all? :)

Again, we have these drawbacks for no real benefit.

[Dave Sexton]

Re: Repetitive XML comments -- what's the point?

Hi,

They are at least for the sake of completion.

If you open compiled documentation for your project and your missing summaries and parameter descriptions it doesn't tell you that
WYSIWYG. It simply tells you that the documentation wasn't finished. IMO, if you leave it out and say, "If the documentation
doesn't exist then it's safe to assume that WYSIWYG", you might get into some trouble if you don't document the things that aren't
implied simply by their name when using that documentation in the future.

The same goes for intellisense, IMO. If I mouse over RemoveNode and it tells me nothing I don't immediately assume that there
aren't any complications when using the method and in many cases I would look into the method's source just to double-check. Now,
I'm not saying that if I saw a summary comment like, "Removes a Node" that it's much more descriptive, but it tells me at a minimum
that the method simply removes a node.

--
Dave Sexton

"tjb" <tjb@invalid.in validwrote in message news:1kx9pi0tzv 467.dlg@tjb.inv alid.invalid...

Peter Macej <peter@helixoft .comwrote:

>>My point is about repetitive comments, not XML comments.

>>
>If you omit <summarytag, you will have no method description in
>IntelliSense . If you omit <paramtag, you will have description for
>this parameter in Intellisense. The same applies for generated
>documentatio n.
>>
>So while comment may seem long or redundant in source code, it is
>necessary for proper generation of IntelliSense and documentation.

>
Again, though, what use is this intellisense documentation if (for all
intents and purposes) it already exists -- within the name of the method,
for example?
>
If I hover over a call to the method "CreateFroz zle" and intellisense pops
up and says, "Creates a frozzle.", I've gained nothing.

[Laurent Bugnion, GalaSoft]

Re: Repetitive XML comments -- what's the point?

Hi,

tjb wrote:

"Peter Bromberg [C# MVP]" <pbromberg@yaho o.nospammin.com wrote:
>

>>The XML Comments "appear" repetitive because you are looking at them in the
>>code window. However, when they get translated into Intellisense or built
>>documentati on such as a CHM Help file, they aren't repetitive at all.
>>Peter

>
>
But wherever you see the comment, you see the method/param name, right?
Thus, they're repetitive everywhere.
>
If I see "Removes a node." in intellisense, I also see "RemoveNode " (the
method name). The summary comment in intellisense tells me nothing more
than the method name does.

Writing code and writing source code documentation require different
skills. Many programmers are very good in C# and very bad in english.
However, I prefer bad documentation to no documentation, especially if
it's accurate, but just badly styled.

HTH,
Laurent
--
Laurent Bugnion, GalaSoft
Software engineering: http://www.galasoft-LB.ch
PhotoAlbum: http://www.galasoft-LB.ch/pictures
Support children in Calcutta: http://www.calcutta-espoir.ch