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" <tj*@invalid.invalidwrote in message news:1k***************@tjb.invalid.invalid...

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

Oct 6 '06 #14

Laurent Bugnion, GalaSoft

Hi,

tjb wrote:

"Peter Bromberg [C# MVP]" <pb*******@yahoo.nospammin.comwrote:

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

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

Oct 6 '06 #15

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.

Oct 6 '06 #16

DeveloperX

tjb wrote:

Peter Macej <pe***@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 "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".

Oct 6 '06 #17

Peter Bromberg [C# MVP]

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

"tjb" wrote:

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

Oct 6 '06 #18

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.

--
Dave Sexton

"Adrian Gallero" <adrian@[nospam]tmssoftware.comwrote in message news:uw****************@TK2MSFTNGP04.phx.gbl...

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.

Oct 6 '06 #19

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.

--

Oct 6 '06 #20

david.boyle

tjb wrote:
<snip>

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.

<snip>

Yup, such comments are a waste of space. I understand there are even
tools that will fill in this sort of completely redundent comment
automatically...oh dear.

Cheers,

Dave

Oct 6 '06 #21

Hi Adrian,

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

How does having no warnings, which are intended to tell you when you are missing documentation, help to acheive the goal of ensuring
that your documentation is good?

I see the warnings as a tool that you can use to flag documentation as "TODO" (properly). You may have other ways of flagging
documentation as being incomplete, and that's acceptible. It's just that you didn't mention them and your post seemed to imply that
poor documentation was acceptible simply to suppress compiler warnings.

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.

I'm not sure I understand what you mean here. Are you suggesting that I shouldn't use warnings to flag documentation as "TODO"?

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

I'm not sure I understand your point here either. The choice, as I see it, has nothing to do with working code. The choice is
simply, "Do I allow VS.NET to notify me when I haven't completed documentation, or do I throw in a stub to suppress the warning and
address the issue later using some other tool?".

I think I've made my POV clear on this. I prefer to use warnings, at least because I don't know of any way to keep track of bad
documentation or that it would supply any advantage over using warnings.

--
Dave Sexton

Oct 6 '06 #22

tjb

I wrote:

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

Actually, I take this one back -- if the comment is repetitive, the comment
and the name are the same anyway, and so if the comment is good then so is
the name.

I'm about to go offline. I'll reply to the newer replies a little later.

Oct 6 '06 #23

Stoitcho Goutsev \(100\)

I've some time ago some transcript of a whiteboard session with Anders
Hejlsberg (I hope everybody know who he is; for the ones that don't this is
the *father* of C#) regarding this issue. It is indeed not very nice that we
need to write the same comments over and over again. As an example when I
override a method I need to copy the comments from the base implementation
and some times I don't have to change anything just because I don't change
the semantic of the method. There are also cases that I need to elaborate
only on the summary or remarks section, but I shouldn't have to write all
teh information for the parameters. Something there should be smart enough
to pick the parts that I haven't changed from the base implementation. The
same (mybe even better example) is the method overloads where we add only
one parameter to the signature.

Here is excerpt of the transcript

"...
Question:

My problem is I've got these XML doc comments that are duplicated. I just
strip off one. I guess it would be a neat language feature to be able to
somehow indicate this is my primary- my big method, right? With all the
parameters. Then the other ones are just going to borrow that XML doc
comment. When XML doc comma,-

Hejlsberg:

Yes, okay. Now that I think is- that's not a bad idea. That yes, they should
be able to share the documentation. I can sympathize with that.
...."
The whole transcript can be found here
http://msdn.microsoft.com/msdntv/tra...ranscript.aspx
--
Stoitcho Goutsev (100)
"tjb" <tj*@invalid.invalidwrote in message
news:11****************@tjb.invalid.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?

Oct 6 '06 #24

Hi Again,

>
How does having no warnings, which are intended to tell you when you
are missing documentation, help to acheive the goal of ensuring that
your documentation is good?

Well, going to practical things, yesterday it helped me. Yesterday I
added a method to a class, I needed it for internal reasons, but it
could be useful to other users too, so I made it public. I was not
thinking in docs at the time and completely forgot to document it. I
found out also yesterday when I made the release build.

Had I had 5000 doc warnings on my code of "things that do not need to
be documented" I would have never found out.

>
I see the warnings as a tool that you can use to flag documentation
as "TODO" (properly). You may have other ways of flagging
documentation as being incomplete, and that's acceptible. It's just
that you didn't mention them and your post seemed to imply that poor
documentation was acceptible simply to suppress compiler warnings.

I think we are not understanding each other here. I am not and never
was speaking of incomplete documentation. Of course, adding stubs to
avoid warning is completely silly, you will never find those stubs
again.

But I was speaking about "redundant comments", and I think this was
what the thread was about. An example: (from actual .NET doc):

String Constructor [C#]
Initializes a new instance of the String class.

Do we really need this extra information? No. But if you do not
document every public constructor this way, and have some hundred
classes, you will get some hundred errors. This will render the warning
completely useless, and when you actually forget to document a method
(as it happened to me yesterday) you will never find out. It is not a
problem it you never forget to document any public thing. But I do
forget sometimes, and this is a very welcome hint.

But note that this is not related *at all* with todo's and stubs.

In my opinion, you should never have hundred of todo's (in fact, in
documentation I prefer to always document before creating the method or
inmediately after, since this is when your ideas are fresh). So, having
some not documented methods because you did not had time to document
them yet will do no harm. You will have some warnings, and they tell
you exactly what things you need to fix. This is exactly what I want.

But if you have 5000 warnings on redundant constructors you did not
documented (becaus ethey were redundant), you will never find out, and
the help this warning can give you is lost.

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.

I'm not sure I understand what you mean here. Are you suggesting
that I shouldn't use warnings to flag documentation as "TODO"?

As you can see from my previous writing, I am suggesting that you
*should* use warning to flag todo documentation. And to do this, you
need to get rid of all the redundant comments.

I'm not sure I understand your point here either. The choice, as I
see it, has nothing to do with working code. The choice is simply,
"Do I allow VS.NET to notify me when I haven't completed
documentation, or do I throw in a stub to suppress the warning and
address the issue later using some other tool?".

Again, not at all. Is "Do I allow VS.NET to notify me that I have 5000
methods that do not need documentation, or do I document those methods
with their obvious explanations so I can actually find what I need to
document?"

I think I've made my POV clear on this. I prefer to use warnings, at
least because I don't know of any way to keep track of bad
documentation or that it would supply any advantage over using
warnings.

As answer to your question, I prefer this too. This is what I have been
saying all of the time. And in fact, I prefer to doument everything
"when it is hot" and not have many todo's in doc.

But if you did not documented all the "creates a new zzz instance"
methods (that was my original point) you would not be able to use the
warnings at all, trying to find something between thousands of warnings.

Well, on the end I think we actually agree here, it is just that we are
speaking of different things. As other poster said, I think the horse
is dead :)

Kind regards,
Adrian.
--

Oct 6 '06 #25

Hi Adrian,

>How does having no warnings, which are intended to tell you when you
are missing documentation, help to acheive the goal of ensuring that
your documentation is good?

Well, going to practical things, yesterday it helped me. Yesterday I
added a method to a class, I needed it for internal reasons, but it
could be useful to other users too, so I made it public. I was not
thinking in docs at the time and completely forgot to document it. I
found out also yesterday when I made the release build.

Had I had 5000 doc warnings on my code of "things that do not need to
be documented" I would have never found out.

I never suggested that warnings represented "things that do not need to be documented". You have misunderstood my reasoning, but
I'm not sure how much clearer I can make it.

Warnings, as I use them, indicate to me that documentation still needs to be added. They do not indicate to me that documentation
does not need to be added. How would that be of any use?

>I see the warnings as a tool that you can use to flag documentation
as "TODO" (properly). You may have other ways of flagging
documentation as being incomplete, and that's acceptible. It's just
that you didn't mention them and your post seemed to imply that poor
documentation was acceptible simply to suppress compiler warnings.

I think we are not understanding each other here. I am not and never
was speaking of incomplete documentation. Of course, adding stubs to
avoid warning is completely silly, you will never find those stubs
again.

That's fine. Your original response implied, IMO, that you were encouraging the additon of documentation such as the example that
the OP supplied simply to suppress compiler warnings. I think now we've cleared up that those were not your intentions.

But I was speaking about "redundant comments", and I think this was
what the thread was about. An example: (from actual .NET doc):

String Constructor [C#]
Initializes a new instance of the String class.

Well, that's one of the reasons why I assumed that you were advocating the use of redundant comments to suppress compiler warnings,
which is normally bad documenation, IMO. The sample documentation is an example of poor documentation, IMO.

BTW, each string constructor overload contains a remarks section and additional information in the summary. Also, some have
examples. These are not good examples of "redundant comments", as I understand it. The particular definition you have cited is on
the "overloads" page which is not directly supported by C# commenting and also includes an example anyway.

Do we really need this extra information? No. But if you do not
document every public constructor this way, and have some hundred
classes, you will get some hundred errors. This will render the warning
completely useless,

I disagree. I believe what's useful about the warnings is that it's telling you that you still have hundreds of undocumented
elements in your project. If you go through each one and add the proper documentation you can eventually document your entire
project and VS.NET will guide you by warning you about the elements that still require documentation.

and when you actually forget to document a method
(as it happened to me yesterday) you will never find out. It is not a
problem it you never forget to document any public thing. But I do
forget sometimes, and this is a very welcome hint.

But note that this is not related *at all* with todo's and stubs.

Well that's one difference right there between our methodologies. You, apparently, are documenting your code while you work. I, on
the other hand, tend to document the code after the code element is finalized (excluding in-line comments) so that I don't have to
constantly review the documentation that I've written to make sure that it's not broken whenever I change the code or refactor.
Compiler warnings are quite useful to me in this respect because they act on a lack of documentation as a "TODO" to remind me,
before release, that all of my code elements need to be documented. I then use all of the warnings to complete the documentation.

This too, I believe, is the reason for some of the misunderstandings we have had.

In my opinion, you should never have hundred of todo's (in fact, in
documentation I prefer to always document before creating the method or
inmediately after, since this is when your ideas are fresh). So, having
some not documented methods because you did not had time to document
them yet will do no harm. You will have some warnings, and they tell
you exactly what things you need to fix. This is exactly what I want.

Ok, so I just wrote about how we think differently on this subject. I prefer to document afterwards in most cases. Planning ahead
before you write code helps out a lot, especially if you have visual diagrams and artifacts to reference. I don't skip xml
documenting because of a lack of time, however. It's simply because the code documentation will probably change and it's just more
to maintain. I'd rather concentrate on the business and technology problems at hand and address documentation later, especially if
the project has already been planned out ahead of time. Then, the code should be fairly easy to document afterwards.

But if you have 5000 warnings on redundant constructors you did not
documented (becaus ethey were redundant), you will never find out, and
the help this warning can give you is lost.

So I think this was the actual point of your original response to the OP?

Again, I don't think that "redundant" documentation is good documentation and this was my concern with your response. In some cases
it's all that's needed but in most cases it's not. For example, adding the list of exceptions thrown by a method or property is not
redundant and is usually required to make good documentation. The warnings are still useful because it allows you to go to each
code element, individually, and verify whether "rendundant" documentation is actually acceptible instead of assuming that every
element in your entire application is simple enough to understand without good, explicit documentation, including exceptions and the
expression of subtleties that might otherwise be ambiguous. If the best you can do is "Constructs a new instance of Type A", then
that's the best you can do. But at least you verified it. I think part of the cause of poor documentation is the assumption that
your making when saying "5000 warnings on redundant constructors".

<snip misunderstandings>

--
Dave Sexton

Oct 6 '06 #26

Dave,

I feel we are both saying the same here, and I am not sure why we are
still discussing this. I will try just once more time:

The "subject" of this thread is
"Repetitive XML comments -- what's the point?"

You might or not might agree that repetitive comments exist, but this
is other subject. I think they exist, as in the parameterless string
constructor example. Yes, it initializes a string class. There is no
much more you can say here that is not said on the "string"
documentation. Adding a comment here is like the classical:

i++; //increment i

Under the original thread, the original poster said that *if* you have
redundant comments, it was better not to document them at all.

What I answered, is that if you do not document even things that need
no documentation, you can not actually use the warnings to find out
things that you didn't document.

That's it. There is nothing about making documentation stubs or
anything. This was about documenting obvious things.

String Constructor [C#]
Initializes a new instance of the String class.

The sample
documentation is an example of poor documentation, IMO.

Well, here is a point I disagree. Adding lots of trivial explanations
because there is nothing else to say is IMHO an example of poor
documentation.

String Constructor [C#]
Initializes a new instance of the String class. The string class is ...
(reinclude all information that is already on the information for the
class, ot other information that will not help you at all to construct
a string)

That is poor documentation. Documentation should be all that is needed,
but no more. If there is nothing to say, say nothing.

>
BTW, each string constructor overload contains a remarks section and
additional information in the summary.

Yep, but I was speaking about the parameterless contructor. Almost
every class has a parameterless constructor, and most of the time what
all you can say about it is "constructs a new instance of MyClass" And
this is good. If the constructor needs more documentation, probably
there is something wrong with it.

These are not good examples of "redundant comments", as I understand
it. The particular definition you have cited is on the "overloads"
page which is not directly supported by C# commenting and also
includes an example anyway.

The comments on the overrloaded methods are different comments. On the
code, you have:

///<summary>
/// Initializes a new instance of the String class.
///</summary>
public String()
{
}

This comment is completely useless, and the fact that the overloads
might have useful comments and examples, does not make this particular
comment more useful.

I disagree. I believe what's useful about the warnings is that it's
telling you that you still have hundreds of undocumented elements in
your project.

Again, I agree 100%, but we are not discussing this. We are discussing

"What do you do if you find a method that (you feel) does not need
documentation?"

I see 3 options:

1) You do not document it. this was what the OP suggested, and I said
that this will not allow you to use the warnings.

2) You state the obvious. This is what I do, and even when I might not
like it much, it works.

3)No method on your code is so straightforward that you can not add
anything that is not obvious. You think long enough, and you find out
you have something to say. If you still don't, you make the method less
straightforward.

do you see any other option? Sometimes reading this, it seems like you
are advocating 3).

Again, I don't think that "redundant" documentation is good
documentation and this was my concern with your response.

Yes, I agree option 2) is the lesser of 3 evils. But IMHO is better
than 1) or 3)

If the best you can do is "Constructs a new instance of Type A",

then that's the best you can do. But at least you verified it. I
think part of the cause of poor documentation is the assumption that
your making

when saying "5000 warnings on redundant constructors".

And this is what I have been saying all along!

Let's recap:
We agree we want 0 warnings on our final (shipping) code. We use
warnings to review what is left, and we try to make the best comments
when we can.

We agree that "If the best you can do is "Constructs a new instance of
Type A", then that's the best you can do. But at least you verified
it."

So we write "constructs a new instance of type A", verified it, and we
get one warning less, that will allow use to focus on the real warnings.

I still do not know what we are discussing about. It seems to me that
all the misunderstandings come form the fact that you assumed that I
was advocating to stub all documentation to claim "zero warnings", but
I never said something like that. In fact, as stated before, I normaly
code documentation with the code, because IME, when you have ideas
fresh is when you document best. If later you refactor, you refactor
the comments too. It is not that hard.

Regards,
Adrian.

Oct 6 '06 #27

Hi Adrian,

We definitely aren't saying the same thing. But I guess we'll just have to agree to disagree.

As for the relevancy of our discussion, I think it applies directly to your response and to the OP. I was hoping to come to an
understanding about the intentions of your original reply and to further analyze the notion of "redundant comments" and how they
relate to compiler warnings on missing comments. Unfortunately, I don't think we are going to come to an agreement on this topic.
I feel that I can't make my POV any clearer as well. If anyone else feels differently I'd be happy to continue the discussion.

Thanks for the discussion thus far.

--
Dave Sexton

"Adrian Gallero" <adrian@[nospam]tmssoftware.comwrote in message news:eb**************@TK2MSFTNGP04.phx.gbl...

Dave,

I feel we are both saying the same here, and I am not sure why we are
still discussing this. I will try just once more time:

The "subject" of this thread is
"Repetitive XML comments -- what's the point?"

You might or not might agree that repetitive comments exist, but this
is other subject. I think they exist, as in the parameterless string
constructor example. Yes, it initializes a string class. There is no
much more you can say here that is not said on the "string"
documentation. Adding a comment here is like the classical:

i++; //increment i

Under the original thread, the original poster said that *if* you have
redundant comments, it was better not to document them at all.

What I answered, is that if you do not document even things that need
no documentation, you can not actually use the warnings to find out
things that you didn't document.

That's it. There is nothing about making documentation stubs or
anything. This was about documenting obvious things.

String Constructor [C#]
Initializes a new instance of the String class.

The sample
documentation is an example of poor documentation, IMO.

Well, here is a point I disagree. Adding lots of trivial explanations
because there is nothing else to say is IMHO an example of poor
documentation.

String Constructor [C#]
Initializes a new instance of the String class. The string class is ...
(reinclude all information that is already on the information for the
class, ot other information that will not help you at all to construct
a string)

That is poor documentation. Documentation should be all that is needed,
but no more. If there is nothing to say, say nothing.

>>
BTW, each string constructor overload contains a remarks section and
additional information in the summary.

Yep, but I was speaking about the parameterless contructor. Almost
every class has a parameterless constructor, and most of the time what
all you can say about it is "constructs a new instance of MyClass" And
this is good. If the constructor needs more documentation, probably
there is something wrong with it.

>These are not good examples of "redundant comments", as I understand
it. The particular definition you have cited is on the "overloads"
page which is not directly supported by C# commenting and also
includes an example anyway.

The comments on the overrloaded methods are different comments. On the
code, you have:

///<summary>
/// Initializes a new instance of the String class.
///</summary>
public String()
{
}

This comment is completely useless, and the fact that the overloads
might have useful comments and examples, does not make this particular
comment more useful.

>I disagree. I believe what's useful about the warnings is that it's
telling you that you still have hundreds of undocumented elements in
your project.

Again, I agree 100%, but we are not discussing this. We are discussing

"What do you do if you find a method that (you feel) does not need
documentation?"

I see 3 options:

1) You do not document it. this was what the OP suggested, and I said
that this will not allow you to use the warnings.

2) You state the obvious. This is what I do, and even when I might not
like it much, it works.

3)No method on your code is so straightforward that you can not add
anything that is not obvious. You think long enough, and you find out
you have something to say. If you still don't, you make the method less
straightforward.

do you see any other option? Sometimes reading this, it seems like you
are advocating 3).

>Again, I don't think that "redundant" documentation is good
documentation and this was my concern with your response.

Yes, I agree option 2) is the lesser of 3 evils. But IMHO is better
than 1) or 3)

> If the best you can do is "Constructs a new instance of Type A",
then that's the best you can do. But at least you verified it. I
think part of the cause of poor documentation is the assumption that
your making
>when saying "5000 warnings on redundant constructors".

And this is what I have been saying all along!

Let's recap:
We agree we want 0 warnings on our final (shipping) code. We use
warnings to review what is left, and we try to make the best comments
when we can.

We agree that "If the best you can do is "Constructs a new instance of
Type A", then that's the best you can do. But at least you verified
it."

So we write "constructs a new instance of type A", verified it, and we
get one warning less, that will allow use to focus on the real warnings.

I still do not know what we are discussing about. It seems to me that
all the misunderstandings come form the fact that you assumed that I
was advocating to stub all documentation to claim "zero warnings", but
I never said something like that. In fact, as stated before, I normaly
code documentation with the code, because IME, when you have ideas
fresh is when you document best. If later you refactor, you refactor
the comments too. It is not that hard.

Regards,
Adrian.

Oct 6 '06 #28

"tjb" <tj*@invalid.invalidwrote in message
news:11****************@tjb.invalid.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.

I agree, for the most part. If the method isn't described well by its name,
or its parameters arent' described well by their names, or the return value
isn't obvious by the method's name, then the method should have an XML
comment. But those situations should be avoided.

Many, if not most, methods are like the one you posted, where the XML
comments are useless, and serve no purpose but to cause real code to scroll
off the bottom of the screen.

///ark

Oct 6 '06 #29

"Dave Sexton" <dave@jwa[remove.this]online.comwrote in message
news:u6**************@TK2MSFTNGP05.phx.gbl...

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.

It really tells you no such thing. There could just as easily be as many
undocumented subtleties going on as if there were no summary comment at all.
Who trusts comments?

The only purpose of Intellisense comments is to help you pick a method when
the name itself isn't clear enough. And that simply points to a different
problem.

///ark

Oct 6 '06 #30

"Peter Bromberg [C# MVP]" <pb*******@yahoo.nospammin.comwrote in message
news:D7**********************************@microsof t.com...

Erm, I think the horse is already dead.

The horse will die when people stop posting, not when one person says they
should stop.

I find it fascinating the number of people who seem to feel that
documentation is an end in itself, rather than as a means to - oh, I dunno -
produce better code faster.

///ark

Oct 6 '06 #31

Hi Mark,

Well I trust comments. Especially if they're my own ;)

I believe that a comment such as "Removes a Node" tells me that the author decidedly placed that comment and so they didn't feel
there was any functionality that couldn't simply be assumed. For instance, I would assume that RemoveNode doesn't popup a
MessageBox or throw an error if the class maintains internal state that is invalid at the time of the call. In the absence of any
documentation at all, I try to make no such assumptions.

Anyway, this is a bad example because RemoveNode naturally has subtleties that need to be addressed in documentation. Alone,
"Removes a Node" might very well be incomplete documentation.

1. Does RemoveNode set the node's Parent property to null?
2. Does RemoveNode cause any events to be raised?
3. Does RemoveNode throw exceptions such as ArgumentNullException or an exception if the object on which the method is called does
not contain the specified node?
4. Does RemoveNode throw an exception if the current state of the object is invalid?
5. Is there a business rule in place that prevents the last node from being removed?

Now I'm not suggesting that one must always document what a method doesn't do, but one or more of the above points should probably
be addressed for any implementation of a RemoveNode method. For that reason, it really shouldn't be used as an example of
"Repetitive XML comments" because alone it's not really a good comment anyway.

There are, I'm sure, good examples of repetitive xml comments that don't seem to add any value but I believe I've made my case
against that idea already.

--
Dave Sexton

"Mark Wilden" <mw*****@communitymtm.comwrote in message news:OR**************@TK2MSFTNGP03.phx.gbl...

"Dave Sexton" <dave@jwa[remove.this]online.comwrote in message news:u6**************@TK2MSFTNGP05.phx.gbl...

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

It really tells you no such thing. There could just as easily be as many undocumented subtleties going on as if there were no
summary comment at all. Who trusts comments?

The only purpose of Intellisense comments is to help you pick a method when the name itself isn't clear enough. And that simply
points to a different problem.

///ark

Oct 6 '06 #32

"Dave Sexton" <dave@jwa[remove.this]online.comwrote in message
news:%2****************@TK2MSFTNGP05.phx.gbl...

>
Well I trust comments. Especially if they're my own ;)

I note the smiley, but do you -really- trust other people's comments?

I believe that a comment such as "Removes a Node" tells me that the author
decidedly placed that comment and so they didn't feel there was any
functionality that couldn't simply be assumed. For instance, I would
assume that RemoveNode doesn't popup a MessageBox or throw an error if the
class maintains internal state that is invalid at the time of the call.
In the absence of any documentation at all, I try to make no such
assumptions.

In my case, I could not make any such assumptions based on the
documentation.

1. Does RemoveNode set the node's Parent property to null?

It had better, otherwise, the code is buggy.

2. Does RemoveNode cause any events to be raised?

Does it matter?

3. Does RemoveNode throw exceptions such as ArgumentNullException or an
exception if the object on which the method is called does not contain the
specified node?

If you're calling the method, and you don't know whether the node is
contained in the container, and you need to know what happens in such a
case, you really need to check the code or the unit tests. You can't rely on
developer documentation to determine this, at least in my experience.

4. Does RemoveNode throw an exception if the current state of the object
is invalid?
5. Is there a business rule in place that prevents the last node from
being removed?

Again, if these were concerns, I'd just read the code. It would be simpler,
shorter, and - most importantly - guaranteed to be accurate.

(Naturally, all of this doesn't apply to library code where the source isn't
available.)

///ark

Oct 6 '06 #33

Hi Mark,

I see the same problem here as in my discussion with Adrian. We disagree on what "good" documentation actually means. If we agreed
on that then we'd most likely agree on how to manage it and what use it would provide.

>Well I trust comments. Especially if they're my own ;)

I note the smiley, but do you -really- trust other people's comments?

Well I trust documentation that is written against the project plans and the finalized code. If I couldn't trust that code
documentation then I wouldn't expect developers to write any of it in the first place. It's all or none then as I see it and I'd
prefer all.

>I believe that a comment such as "Removes a Node" tells me that the author decidedly placed that comment and so they didn't feel
there was any functionality that couldn't simply be assumed. For instance, I would assume that RemoveNode doesn't popup a
MessageBox or throw an error if the class maintains internal state that is invalid at the time of the call. In the absence of any
documentation at all, I try to make no such assumptions.

In my case, I could not make any such assumptions based on the documentation.

I believe you have made it clear that it is a trust issue. I, on the other hand, believe that I can trust documentation otherwise I
feel that it's meaningless and should be omitted completely - so long MSDN! ;) It's not fair to ask developers to somehow choose
the documentation that is "good" and the documentation that is "bad". It should all be good.

<snip rhetorical questions:)

Ok, so they weren't exactly rhetorical but I really didn't expect you to argue them either. Seriously, I'm suprised. I'll just
agree to disagree on those points as well. I believe this too is tied into our difference of opinion concerning the meaning of
"good" documentation.

--
Dave Sexton

Oct 6 '06 #34

Willem van Rumpt

tjb wrote:

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.

I know what you're trying to say, but I simply don't have an issue with
it. It doesn't disturb me when reading code.

You might also argue that the sample you provided is poorly documented:
Does it throw an exception if the node parameter is null? If so, why
isn't it documented; if not, what does it do in the case of null values?
Are there preconditions? postconditions? Side effects? Are there methods
that provide similar functionality, to offer the caller a choice (think
"Add" vs. "Insert") that might be more appropriate to the situation? Are
there cross references to other classes?

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

I've rarely seen a significant change in a public method leading to just
updating the comment. In my experience, this involves lot's of greps,
curses, and prayers.

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?

It's not only consistency (but part is, admittedly. In my case, "habit"
might also be a good word for it). The use of xml comments is also (or
perhaps even more) there to provide documentation for those who *don't*
have the source. Think of stripping the descriptions from the framework
classes and methods whose names are obvious (and a lot them are). Would
you be happy and confident to use them?

I document everything with (at least) a visibility from protected and
up, regardless of the complexity of the method, if only to provide
complete documentation for those who don't have access to the source.
Even *with* access to the source, complete and accurate documentation
might give you enough information so you don't have to go to the source.

--
Willem van Rumpt

Oct 6 '06 #35

"Dave Sexton" <dave@jwa[remove.this]online.comwrote in message
news:Ot**************@TK2MSFTNGP05.phx.gbl...

I see the same problem here as in my discussion with Adrian. We disagree
on what "good" documentation actually means.

I don't think we disagree about what it means so much as how often it
exists. :)

However, I admit I'm heavily in the "anti-documentation" camp (an
exaggerated position) that says that the time spent making documentation
complete is better spent writing new code and new tests.

Well I trust documentation that is written against the project plans and
the finalized code. If I couldn't trust that code documentation then I
wouldn't expect developers to write any of it in the first place.

Well, developers do write documentation, and in my experience, it's never
really trustworthy.

I believe you have made it clear that it is a trust issue. I, on the
other hand, believe that I can trust documentation otherwise I feel that
it's meaningless and should be omitted completely

That's pretty much my position. So I guess we do agree. :) The question is,
on which side of your "otherwise" does most reality fall?

so long MSDN! ;)

MSDN is completely different from XML comments. First, it's for library
code, which can't be inspected. Second, it's written by professional
documentors, who get paid for documenting, not for writing code.

It's not fair to ask developers to somehow choose the documentation that
is "good" and the documentation that is "bad". It should all be good.

Or it's a waste of time to have developers spend resources on it.

///ark

Oct 6 '06 #36

"Willem van Rumpt" <someplace@somewherewrote in message
news:eH****************@TK2MSFTNGP03.phx.gbl...

>
You might also argue that the sample you provided is poorly documented:
Does it throw an exception if the node parameter is null? If so, why isn't
it documented; if not, what does it do in the case of null values?
Are there preconditions? postconditions? Side effects?

These things are best answered by reading the code. That's the ultimate
source of truth, after all.

Are there methods that provide similar functionality, to offer the caller
a choice (think "Add" vs. "Insert") that might be more appropriate to the
situation? Are there cross references to other classes?

However, I do agree that these are good candidates for documentation.

Even *with* access to the source, complete and accurate documentation
might give you enough information so you don't have to go to the source.

It's so easy to "go to the source" in modern IDEs that the risk in trusting
uncompilable documentation is simply too great.

But I hope that most of us don't really disagree that an XML comment
"Removes node" on a method called RemoveNode provides nothing, but is
extremely common. It clearly provides a comfort zone for many developers.
It's these -repetitive- XML comments that are worthless.

///ark

Oct 6 '06 #37

Noah Sham

"Mark Wilden" <mw*****@communitymtm.comwrote in message
news:Og**************@TK2MSFTNGP03.phx.gbl...

>
These things are best answered by reading the code. That's the ultimate
source of truth, after all.

Amen. If you had time to write comments then you had time to write code
that didn't need a comment.

Oct 6 '06 #38

Hi Mark,

(Now I know we're a bit off-topic, but I just can't help discussing this because I find the subject quite interesting. Instead of,
"Repetitive XML comments - what's the point?" it seems to be a discussion of, "Good/complete XML comments - what's the point?")

<snip>

However, I admit I'm heavily in the "anti-documentation" camp (an exaggerated position) that says that the time spent making
documentation complete is better spent writing new code and new tests.

Yep. We disagree on that :)

I'm definately for writing new code and tests, but not at the expense of substantial documentation. I see it like this:

[example]
If you are hired to develop a solution for a business and you realize they have no documentation of their rules or processes, you
spend a lot of time trying to extract that information from the users and existing infrastructure, which can be a tedious process
that is full of assumptions. It takes analyses, refinement and reiteration to finally be able to build up the documentation that
acurately describes the business processes and requirements for the new software.

In the software world, I think it's even more important to have documentation (of the code) regardless of whether it's "library" or
business code, so that developers who are not part of the project during development, peers, managers who are not familiar with code
in general, and the author themselves can understand what was done at a later time without having to wade through thousands of lines
of code or make assumptions on its behavior. I'd much rather look up a question I had about the behavior of a method in an
MSDN-like compiled help file with a contents, search, index and glossary than to try to locate the method in code just to learn that
the behavior has been extracted into another class based on some pattern that was implemented without my prior knowledge. Now, I
have to try to follow the pattern so I can find out what causes the behavior that I have witnessed, and in many cases it becomes
trial and error until I finally assume that I've figured it all out. Much easier, IMO, to make a note of the functionality in the
remarks section after the code has been finalized. Now I'm not suggesting that good documentation can completely alleviate the need
to look at the source in all circumstances, but I think that's what developers/documentors should strive to achieve. If you planned
the project, understand its design and the business requirements that it's addressing then documenting code shouldn't be a difficult
process at all.

>Well I trust documentation that is written against the project plans and the finalized code. If I couldn't trust that code
documentation then I wouldn't expect developers to write any of it in the first place.

Well, developers do write documentation, and in my experience, it's never really trustworthy.

I think good developers should be able to understand and appropriately comment on there code. After all, you expect them to write
appropriate in-line comments, right? IMO, if code contains at least one in-line comment it probably requires some higher-level
documentation to describe its overall behavior. Even if that behavior is simply, "throws ArgumentNullException".

>I believe you have made it clear that it is a trust issue. I, on the other hand, believe that I can trust documentation
otherwise I feel that it's meaningless and should be omitted completely

That's pretty much my position. So I guess we do agree. :) The question is, on which side of your "otherwise" does most reality
fall?

Well I trust documentation that I write and I expect other developers to write trustworthy documentation as well. In my experience,
most developers feel just like you do about the subject and fail to write good documentation or any documentation at all, but that
doesn't make it right ;)

I must admit, however, that I don't always follow my own advice. I work on hobby-projects all the time, by myself, and I hardly
document anything unless I finish something that I think I can reuse. I find that in many cases I struggle to understand code that
I had written previously due to poor or absent documentation. The reason why I don't document in these cases is because I'm usually
developing in a RAD-style and therefore at the time I tend to value new code and testing over documentation, just like you.

>so long MSDN! ;)

MSDN is completely different from XML comments. First, it's for library code, which can't be inspected. Second, it's written by
professional documentors, who get paid for documenting, not for writing code.

I'm sure you're right about the professional documentors, but that doesn't change the fact that it parallels the generation of
compiled help files for custom code. I don't believe that it being a library of code matters either. Does this mean that you only
support the documentation of .DLLs but not .EXEs? Are they not both code assemblies that, for all intensive purposes, do exactly
the same thing and require an equal amount of documentation? After all, they are both "released" at some point, which means that
somebody else just might want to understand the code at a later time and might not have the source or even understand the source for
that matter.

<snip>

--
Dave Sexton

Oct 6 '06 #39

Willem van Rumpt

Mark Wilden wrote:

>
It's so easy to "go to the source" in modern IDEs that the risk in trusting
uncompilable documentation is simply too great.

Sorry, I've should've been more clear. "Go The Source" only works if you
actually *have* the source, which might not me the case in, for
instance, third party software. Providing documentation for
"RemoveNode()" might be repetitive, but is essential for those who only
have access to your libraries and not your source (and I don't consider
Reflector to be a valid substitute ;) ).

But even in a team environment: I don't want developers to "Go To The
Source", I want them to read the documentation. If you hire new
programmers, do you want them to dive into the source to find out the
intracies for themselves, or do you want to present them with the
documentation? I prefer the last.

But I hope that most of us don't really disagree that an XML comment
"Removes node" on a method called RemoveNode provides nothing, but is
extremely common. It clearly provides a comfort zone for many developers.
It's these -repetitive- XML comments that are worthless.

We agree, and disagree :).

It's a programmers job to document his source properly. My personal
experience is that repetitive documentation is not there because there's
nothing to document, it's there because it was done hastily or as an
afterthought (and I'm guilty on all charges).

Like I said in my original reply, the documentation doesn't bother me
when reading source. It's "offline" reading what interests me: Even
without The Source, I'm able to find out what the interface has to offer
me. Add a reference, and code away.

--
Willem van Rumpt

Oct 6 '06 #40

Hi Noah,

Amen. If you had time to write comments then you had time to write code that didn't need a comment.

So does that mean it's possible to always write code that doesn't require in-line comments either?

--
Dave Sexton

"Noah Sham" <no******@verizon.netwrote in message news:O3*************@TK2MSFTNGP05.phx.gbl...

>
"Mark Wilden" <mw*****@communitymtm.comwrote in message news:Og**************@TK2MSFTNGP03.phx.gbl...
>>
These things are best answered by reading the code. That's the ultimate source of truth, after all.

Amen. If you had time to write comments then you had time to write code that didn't need a comment.

Oct 6 '06 #41

Willem van Rumpt

Noah Sham wrote:

>
Amen. If you had time to write comments then you had time to write code
that didn't need a comment.

So your code is commentless?

--
Willem van Rumpt

Oct 6 '06 #42

Bruce Wood

Stoitcho Goutsev (100) wrote:

I've some time ago some transcript of a whiteboard session with Anders
Hejlsberg (I hope everybody know who he is; for the ones that don't this is
the *father* of C#) regarding this issue. It is indeed not very nice that we
need to write the same comments over and over again. As an example when I
override a method I need to copy the comments from the base implementation
and some times I don't have to change anything just because I don't change
the semantic of the method. There are also cases that I need to elaborate
only on the summary or remarks section, but I shouldn't have to write all
teh information for the parameters. Something there should be smart enough
to pick the parts that I haven't changed from the base implementation. The
same (mybe even better example) is the method overloads where we add only
one parameter to the signature.

Here is excerpt of the transcript

"...
Question:

My problem is I've got these XML doc comments that are duplicated. I just
strip off one. I guess it would be a neat language feature to be able to
somehow indicate this is my primary- my big method, right? With all the
parameters. Then the other ones are just going to borrow that XML doc
comment. When XML doc comma,-

Hejlsberg:

Yes, okay. Now that I think is- that's not a bad idea. That yes, they should
be able to share the documentation. I can sympathize with that.
..."
The whole transcript can be found here
http://msdn.microsoft.com/msdntv/tra...ranscript.aspx

There are two issues here. I think that Anders was addressing only the
first, not the second. I've mentioned both as enhancement requests to
C#, and mentioned them in C# chats, but gotten nowhere. The two issues
are:

Issue #1: Overloads. You have three overloads, one of which takes all
five arguments, the other two provide shorter argument lists with
defaulting. Why can't I write comments only for the one that takes all
five arguments, then put some marker on the other overloads that they
should take the bulk of their documentation from the one that takes
five arguments, together with some quick notes about what the
defaulting behaviour is? This is so common and a waste of time and
space updating comments for all X overloads, particularly for
constructors.

Issue #2: Overrides. I inherit from a class and override some of its
methods, but don't significantly change behaviour. Why can't I inherit
the documentation, too, and change the doc only for the things that
changed? This is a more complicated problem, particularly when combined
with the first issue.

As I said, I've never gotten any satisfaction from pressing either of
these issues with the C# team. I do hope that someday they address one
or both of them, because this doc really _is_ useless: it's copied from
one method to another... copy... paste... copy... paste. Ugh.

Oct 6 '06 #43

"Noah Sham" <no******@verizon.netwrote in message
news:O3*************@TK2MSFTNGP05.phx.gbl...

If you had time to write comments then you had time to write code that
didn't need a comment.

That's a very neat way of putting it.

///ark

Oct 6 '06 #44

"Dave Sexton" <dave@jwa[remove.this]online.comwrote in message
news:ub**************@TK2MSFTNGP05.phx.gbl...

>
[example]
If you are hired to develop a solution for a business and you realize they
have no documentation of their rules or processes, you spend a lot of time
trying to extract that information from the users and existing
infrastructure, which can be a tedious process that is full of
assumptions. It takes analyses, refinement and reiteration to finally be
able to build up the documentation that acurately describes the business
processes and requirements for the new software.

And then a couple of months go by and the documentation is obsolete. Because
we're not paid to keep it up to date - we're paid to deliver functionality.
Now, if there were professional analysts and technical writers employed by
the company, and their paycheck depended on the accuracy of that
documentation, then it would be useful beyond the needs of that one
solution.

In the software world, I think it's even more important to have
documentation (of the code) regardless of whether it's "library" or
business code, so that developers who are not part of the project during
development, peers, managers who are not familiar with code in general,
and the author themselves can understand what was done at a later time
without having to wade through thousands of lines of code or make
assumptions on its behavior.

I've never worked in such a place. Yet I've worked in places that made
money. How could that be? The answer is that documentation, while desirable,
is less desirable than code.

Now I'm not suggesting that good documentation can completely alleviate
the need to look at the source in all circumstances, but I think that's
what developers/documentors should strive to achieve.

As opposed to providing business value? You can't have everything (where
would you put it?).

If you planned the project, understand its design and the business
requirements that it's addressing then documenting code shouldn't be a
difficult process at all.

Actually, it is, else people would do it.

I think good developers should be able to understand and appropriately
comment on there code. After all, you expect them to write appropriate
in-line comments, right?

No, I don't. At my shop, inline comments are forbidden (with rare
exceptions). Tim Ottinger wrote a good blog entry about "comments as
excuses." Inline comments are a way of making excuses for sloppy / confusing
/ complicated code that should be refactored.

Now, sometimes such code is necessary. In that case, we use a special label
and the comment is signed and dated. It's an admission that the code should
be improved.

IMO, if code contains at least one in-line comment it probably requires
some higher-level documentation to describe its overall behavior. Even if
that behavior is simply, "throws ArgumentNullException".

I don't see the benefit of that, at all.

Well I trust documentation that I write and I expect other developers to
write trustworthy documentation as well.

You "expect" it, but since you agree it doesn't happen, isn't this kinda
wishful thinking?

In my experience, most developers feel just like you do about the subject
and fail to write good documentation or any documentation at all, but that
doesn't make it right ;)

At the end of the day, what's right is what produces business value. I
suspect that most code -should- be heavily commented, but that's because
most code is confusing crap - but that's another issue.

I find that in many cases I struggle to understand code that I had written
previously due to poor or absent documentation. The reason why I don't
document in these cases is because I'm usually developing in a RAD-style
and therefore at the time I tend to value new code and testing over
documentation, just like you.

I'm a strong believer in refactoring. My mornings are usually spent making
the previous afternoon's code better. So I don't usually have trouble
understanding my code. In fact, sometimes I look at ten-year-old code I've
written and mourn that it's so good. It seems that I should have improved
more over that time. :)

>Does this mean that you only support the documentation of .DLLs but not
.EXEs? Are they not both code assemblies that, for all intensive purposes,
do exactly the same thing and require an equal amount of documentation?

Well, you can't really call into .EXEs, right?

Oct 6 '06 #45

Hi Bruce,

<snip>

Issue #1: Overloads. You have three overloads, one of which takes all
five arguments, the other two provide shorter argument lists with
defaulting. Why can't I write comments only for the one that takes all
five arguments, then put some marker on the other overloads that they
should take the bulk of their documentation from the one that takes
five arguments, together with some quick notes about what the
defaulting behaviour is? This is so common and a waste of time and
space updating comments for all X overloads, particularly for
constructors.

I do this now using the "include" element, which allows me to reference external xml documents. I must say that being able to
define an external document to share common parameter definitions has proved to be quite useful and xpath makes it easy to organize.
However, it would be nice as a language feature but I'm not sure that it's possible.

Issue #2: Overrides. I inherit from a class and override some of its
methods, but don't significantly change behaviour. Why can't I inherit
the documentation, too, and change the doc only for the things that
changed? This is a more complicated problem, particularly when combined
with the first issue.

I completely agree with this one! The C# team should acknowledge this as something that would save time and effort when documenting
code, if in fact it's possible.

As I said, I've never gotten any satisfaction from pressing either of
these issues with the C# team. I do hope that someday they address one
or both of them, because this doc really _is_ useless: it's copied from
one method to another... copy... paste... copy... paste. Ugh.

That's a shame. Well if it's any consolation, you're definitely not the only one that feels that way :)

--
Dave Sexton

Oct 6 '06 #46

"Willem van Rumpt" <someplace@somewherewrote in message
news:%2****************@TK2MSFTNGP04.phx.gbl...

>
Sorry, I've should've been more clear. "Go The Source" only works if you
actually *have* the source, which might not me the case in, for instance,
third party software.

I already addressed this, Willem - I agree that if you don't have the
source, you need documentation. This thread is about the knee-jerk practice
of adorning methods with their own names restated in "documentation."

But even in a team environment: I don't want developers to "Go To The
Source", I want them to read the documentation. If you hire new
programmers, do you want them to dive into the source to find out the
intracies for themselves, or do you want to present them with the
documentation? I prefer the last.

I want new programmers to read the code, because 1) the code is always
right, 2) the documentation is never up-to-date and is often even wrong, and
3) reading code is best way to learn how to program and how the team
programs.

It's a programmers job to document his source properly.

That's begging the question. You can't just make such a statement, since
that's precisely what's under disagreement.

Like I said in my original reply, the documentation doesn't bother me when
reading source. It's "offline" reading what interests me: Even without The
Source, I'm able to find out what the interface has to offer me. Add a
reference, and code away.

If you trust it.

///ark

Oct 6 '06 #47

"Willem van Rumpt" <someplace@somewherewrote in message
news:eV**************@TK2MSFTNGP04.phx.gbl...

Noah Sham wrote:

>Amen. If you had time to write comments then you had time to write code
that didn't need a comment.

So your code is commentless?

This is not as heretical as it might sound. Especially among agile
developers, comments in code are often felt to be a sign that the code is
not clear. The blocks are too long, or they do too much, or they don't use
good identifiers, or they're prematurely optimized, etc.

Complicated code needs to be commented. Complicated code should be avoided
wherever possible.

See http://butunclebob.com/ArticleS.TimO...pologizeIncode and
http://c2.com/cgi/wiki?ToNeedComments

///ark

Oct 6 '06 #48

Bruce Wood

tjb wrote:

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?

There have been oodles of other reactions to this, so I'll try not to
duplicate what has been said. I have two points to make, which I hope
are new(ish).

First, comments are supposed to add an essential element to the code:
the code tells you what the programmer *did*. Comments tell you what
the programmer *meant to do*. Arguably, this latter function is also
served by unit tests, but the documentation *should be* a quick summary
of precisely what the method was meant to do. If it's blindingly
obvious, then that's great, but at least the developer wrote the doc so
you know that he, too, agreed that this method is as simple as it looks
at first glance.

In other words, code without documentation is missing one critical
piece of information: is what the code is currently doing what the
programmer intended it do? Or is it a mistake?

Those here who say that they don't trust documentation and read the
code instead, I'm sorry: I don't believe you. I don't trust
documentation, either. However, what I mean by that is that I read the
documentation, and then evaluate whether it: a) looks complete and
detailed, and b) given what I'm after (which is usually tracking down a
bug) does it seem that the documentation is accurate? If the
documentation seems reasonably clear and it seems unlikely that the
method in question could be the source of the problem, I move on. I
can't imagine that programmers who "don't trust documentation" read
every line of every method they come across while looking for a bug.
I'm guessing that, like me, they read the doc, but warily,
half-expecting it to be inaccurate. It's a guide, not the gospel truth.

That said, when I find a method for which the doc isn't complete, or
which doesn't clearly state what the method really does, I *update the
doc*. No matter who wrote it (and often it was me who wrote it). I see
it as my job to maintain the documentation (the statement of what
*should* be happening in the code) as it is my job to maintain the code
(which makes things happen). If methods have bad doc, I improve the
doc, just as if methods have missing unit tests, I add them. I do that
because I eventually want the comments to do a good job of expressing
the intent of the method, so that later they'll help me decide how to
fix bugs.

Second, there are always those routines that are so obvious and so
simple that they really don't require header comments, so why write the
comments? I will offer another reason beyond those already given by
other posters: discipline. Simply put, people (and thus programmers)
tend to settle into the lowest common denominator of sloth. Yes, it's
probably true that very simple methods don't need even the minimal
documentation that the triple-slash template asks for. However, if you
say to your team that they don't need to document trivial methods, then
shortly thereafter the bar on what constitutes "trivial" will be
lowered to include methods that are a little more complex, but which
one can still guess at what they do without any help. Then the bar will
be lowered further, then further.... The point is that people being as
they are, it's often a good idea to say, "You have to document every
single method" rather than make exceptions and watch the slow slide
into "no documentation".

Oct 6 '06 #49