Comments on XML Documentation Comments (no pun intended)

[C# Learner]

What are your views on XML documentation comments?

I always comment every class using <summary> tags, and comment *some*
methods. A lot of C# code that I've seen written by others uses
appropriate XML documentation comments for *every* method.

What do you think about this? Should _every_ method (including private
ones, for example) be commented?

 

[Rick Strahl [MVP]]

Documenting a class is not all that useful in most cases. It makes more
sense to document the functionality which sits in methods.

I personally try to document everything although I use a more formal
approach with Help Builder (www.west-wind.com/wwhelp/) into which I import
the Xml documentation and then usually further document it there.

It all depends on who the docs are for, but generally the more the merrier
<g>.

+++ Rick ---

--

Rick Strahl
West Wind Technologies
http://www.west-wind.com/
http://www.west-wind.com/weblog/

 

[Erik Frey]

Thanks for your reply.

Hmm... I've still not fully made up my mind about how far to take the
XML documentation comments thing. As I see it currently, commenting
only *some* methods and not others looks a bit "odd". I guess my mind
is trying to treat the comments as method delimiters, in a way.

Is this code that will eventually be distributed, or reviewed by someone
else? If so, comment -every- method with summary and param tags - be brief
and concise. Then, pick and choose the more important methods to include
stuff like example tags, if you plan on building proper documentation.

Again, it depends on what you are going to do with your code.

Erik

 

[C# Learner]

Is this code that will eventually be distributed, or reviewed by someone
else? If so, comment -every- method with summary and param tags - be brief
and concise. Then, pick and choose the more important methods to include
stuff like example tags, if you plan on building proper documentation.

Again, it depends on what you are going to do with your code.

Well, what I'm thinking here is /general/ code written by me, which is
basically code that only *I* will maintain.

I think, for this context, I'll stick to only using method comments when
the name of the method can't describe it enough. For anything I give
out I'll take your advice.

Thanks.

 

[Jon Skeet [C# MVP]]

What are your views on XML documentation comments?

I always comment every class using <summary> tags, and comment *some*
methods. A lot of C# code that I've seen written by others uses
appropriate XML documentation comments for *every* method.

What do you think about this? Should _every_ method (including private
ones, for example) be commented?

Yes, I believe so. I document absolutely everything, with the exception
of fields which solely exist to back properties - assuming that the
description of the field would be the same as for the property.

Don't forget that documentation isn't just helpful to other people -
it's likely to be helpful to you if you come back to the code in a
year's time. That's why even private methods should be documented.

 

[C# Learner]

Yes, I believe so. I document absolutely everything, with the exception
of fields which solely exist to back properties - assuming that the
description of the field would be the same as for the property.

Interesting to know.

Don't forget that documentation isn't just helpful to other people -
it's likely to be helpful to you if you come back to the code in a
year's time. [...]

In fact that's what was on my mind when I started this thread.

[...] That's why even private methods should be documented.

I'll give a try - documenting everything in the little project I
released as open-source and see what I think.

As a side thought, I think code writing /style/ occupies my mind too
often

Thanks for the reply.