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]

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.

 

[Peter Macej]

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

 

[tjb]

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]

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.

 

[Guest]

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

 

[Mark Jerde]

The purpose is generating documentation.

"Creating a Chm build using Sandcastle"
https://blogs.msdn.com/sandcastle/archive/2006/07/29/682398.aspx

-- Mark

 

[tjb]

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]

My point is about repetitive comments, not XML comments.

If you omit <summary> tag, you will have no method description in
IntelliSense. If you omit <param> tag, 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.

 

[tjb]

If you omit <summary> tag, you will have no method description in
IntelliSense. If you omit <param> tag, 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 "CreateFrozzle" and intellisense pops
up and says, "Creates a frozzle.", I've gained nothing.

 

[tjb]

If I hover over a call to the method "CreateFrozzle" 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 \)]

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]

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.

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)


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]

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.

 

[Laurent Bugnion, GalaSoft]

Hi,

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

 

[Adrian Gallero]

Hi,

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?

I have a very simple reason for this. If you do not comment *every*
public method and you are generating xml comments, you will get a
warning that some methods do not have comments.

This is a very handy warning and I do not want to turn it off, since
sometimes in a hurry you might forget to document a method (or class,
or whatever), and without this warning you won't wind it until much
later.

And the only solution to make this warning useful is to have 0
warnings, and this means documenting every single public thing. Yes
sometimes it is a pain (especially on long enumerated types that are
self describing) but a necessary evil IMHO.

Regards,
Adrian.

 

[DeveloperX]

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 "CreateFrozzle" and intellisense pops
up and says, "Creates a frozzle.", I've gained nothing.

I sort of agree with you, in the sense comments should be meaningful
and not stating the obvious.
//Set c to 1
c = 1;
sort of thing is pointless but
//element 0 is a holding node for bunnies, start at 1, do not touch 0
or the bunnies will get you!
c=1;
conveys something useful.

Your example I feel falls into the first example's category. But if you
compare that with, for example the text on the ArrayList for remove it
says:
"The System.object to remove from the System.Collections.ArrayList. The
value can be null."
The value of the description is added with the last sentence. And
honestly, if all it did was remove a node with no additional caveats or
hints, it would be helpful to know that by having a generic "Removes
object from list".

 

[Guest]

Tjb,
Erm, I think the horse is already dead.
Cheers.
Peter

--
Co-founder, Eggheadcafe.com developer portal:
http://www.eggheadcafe.com
UnBlog:
http://petesbloggerama.blogspot.com

 

[Dave Sexton]

Hi Adrian,

I don't agree with your reasoning. The documentation that the OP has sampled is very poor. It still leaves a number of questions
that can be asked of the method's behavior. In certain circumstances there might not be much more to tell and at least having the
documentation present is useful, as I mentioned in a related post, but ensuring that documentation is present simply to suppress a
compiler warning surely doesn't add any value.

IMO, I would rather have the warning present with no documentation then no warning with poor documentation. Poor documentation is a
bit harder to identify than no documentation at all.

 

[Adrian Gallero]

Hi Dave,

ensuring
that documentation is present simply to suppress a compiler warning
surely doesn't add any value.

In my opinion, it surely does. Of course having "no warnings" will not
ensure your documentation is good at all, but it is one of the multiple
things that can help achieve this goal.

You can apply this to any warning you like. Ensuring that you do not
have any "<insert your favorite hint/warning here>" on your code will
not guarantee that your code works at all, but it can help you detect
mistakes. And we all make mistakes.

IMO, I would rather have the warning present with no documentation
then no warning with poor documentation. Poor documentation is a bit
harder to identify than no documentation at all.

I would also prefer a program that works and is full of compiler and
fxcop warnings that one that doesn't work and has no warnings. But if I
have to choose, I prefer a program that works *and* has no warnings.

Regards,
Adrian.



--