Repetitive XML comments -- what's the point?

[david.boyle]

tjb wrote:

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

 

[tjb]

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.

 

[Dave Sexton]

Hi Adrian,

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

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.

 

[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/transcripts/20040624csharpahTranscript.aspx

 

[Adrian Gallero]

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.

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.


--

 

[Dave Sexton]

Hi Adrian,

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

 

[Adrian Gallero]

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.

 

[Dave Sexton]

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

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.

 

[Mark Wilden]

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

 

[Mark Wilden]

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

 

[Mark Wilden]

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

 

[Dave Sexton]

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.

 

[Mark Wilden]

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

 

[Dave Sexton]

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.

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.

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.

 

[Willem van Rumpt]

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.

 

[Mark Wilden]

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

 

[Mark Wilden]

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

 

[Noah Sham]

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.

 

[Dave Sexton]

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

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

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.

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>

 

[Willem van Rumpt]

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.