Ideas on commenting code ..

  • Thread starter Thread starter Anders Borum
  • Start date Start date
A

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)?
 
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
 
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!
 
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
 
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
 
Back
Top