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/
----------------------------------
Making waves on the Web
"C# Learner" <cs****@learner.here> wrote in message
news:um**************@tk2msftngp13.phx.gbl...

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?

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

Erik Frey wrote:

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.