Ideas on commenting code ..

[Anders Borum]

Hello!

I was wondering if there are any guidelines to documenting our C# code?

I'm not talking about the actual syntax for the Xml markup we add to the
classes, methods etc., but general guidelines for how the text should be
presented (aside from looking at the .NET framework obviously)?

--
venlig hilsen / with regards
anders borum
--

[Rakesh Rajan]

Hi Anders,

AFAIK there are no guidelines on commenting. I usually go to MSDN and find
out how MS has documented an entity.
For example, if I am documenting an enumeration, then I would go to some
enum in MSDN (like MessageBoxIcon or so) and find out the tense, sentence
formation etc. used and then follow that in my documentation.

HTH,
Rakesh Rajan

"Anders Borum" wrote:

Hello!

I was wondering if there are any guidelines to documenting our C# code?

I'm not talking about the actual syntax for the Xml markup we add to the
classes, methods etc., but general guidelines for how the text should be
presented (aside from looking at the .NET framework obviously)?

--
venlig hilsen / with regards
anders borum
--

[Anders Borum]

Hi Rakesh

This is also the approach I'm currently using, but thought I'd ask the
community for pointers. Documenting code is very important and should be
emphasized to the programmers (in my oppinion). Maybe I should write a small
guide and put it online .. hmm!

--
venlig hilsen / with regards
anders borum
--

[Rakesh Rajan]

Hi Anders,

This is very true.

Do go ahead - I feel we really need some ref. which puts down guidelines on
how the language should be while documenting with respect to different
constructs.

Regards,
Rakesh Rajan

"Anders Borum" wrote:

Hi Rakesh

This is also the approach I'm currently using, but thought I'd ask the
community for pointers. Documenting code is very important and should be
emphasized to the programmers (in my oppinion). Maybe I should write a small
guide and put it online .. hmm!

--
venlig hilsen / with regards
anders borum
--

[Bob Powell [MVP]]

I recently wrote a snippet in my blog that deals with this. There is a C#
example available which illustrates the styles I use. I have been creating
developer tools that provide source code for over eight years now so I'm
used to having people looking at my stuff.

I use NDoc to take the generated XML and format it into an MSDN style help
file. I find this method very effective.

http://bobpowelldotnet.blogspot.com/
--
Bob Powell [MVP]
Visual C#, System.Drawing

Answer those GDI+ questions with the GDI+ FAQ
http://www.bobpowell.net/gdiplus_faq.htm

The GDI+ FAQ RSS feed: http://www.bobpowell.net/faqfeed.xml
Windows Forms Tips and Tricks RSS: http://www.bobpowell.net/tipstricks.xml
Bob's Blog: http://bobpowelldotnet.blogspot.com/atom.xml


"Anders Borum" <[e-mail]> wrote in message
news:e$**************@TK2MSFTNGP15.phx.gbl...

Hello!

I was wondering if there are any guidelines to documenting our C# code?

I'm not talking about the actual syntax for the Xml markup we add to the
classes, methods etc., but general guidelines for how the text should be
presented (aside from looking at the .NET framework obviously)?

--
venlig hilsen / with regards
anders borum
--

[Anders Borum]

Hello Bob,

Thanks for pointing to your site. I'll check your ideas out!

--
venlig hilsen / with regards
anders borum
--