XML Documentation...

I

IceAzul

Freshman
Joined
Jun 7, 2005
Messages
43
Does anyone have any tips on how the descriptions should be formed? Is there some sort of guildeline on how to write the documentation?
 
I try to model my documentation after the MSDN, but you should do whatever works best for you and your team. Some specific points that I keep in mind are things like trying not to repeat myself (DRY principle: there’s already a lot of information loaded into a method declaration) and tell why not necessarily what and almost never how. I also try to look at the XML comments as simple contracts. If I get good information that looks like X, I'll do this otherwise, I'll do that.

The bottom line really comes down to considering your need. You'll write documentation a lot differently for a framework API than you would for a one-off personal tool. Consider your audience and try to write the documentation for them.
 
Consider your audience and try to write the documentation for them.
Click to expand...

I whole-heartedly agree with the last line - there's NO point in writing documentation unless you know your intended audience. Write it from that point of view. For simple C# method/class comments, you might try out Ghost Doc. I absolutely love it, especially for well named methods and parameters.
http://www.roland-weigelt.de/ghostdoc/

I also like to have a folder in each assembly called Documentation. I generally have at least a readme.txt and possibly a few word docs. I like to have about one to three pages of high level "here's what happening in this assembly and the important classes" type of documentation. Even for UI assemblies this helps. I gear that documentation for a developer who has been with my company for a year or so and knows their way around, but may not know didly about that assembly. I also try to think about what I would want to see if I didn't touch the code for a year or more.

If there are any particular "weirdnesses" or debates about a particular decision (should this class store it's data in variables or a DataSet, for example), I like to document the choices and my reasons for choosing one. I never quite remember why I went one route later on and I think "the grass is greener on the other side" and want to switch, only later to find out that I did have good reasons for going one route vs the other.

-ner
 
Just one more question (there is a theme here), does anyone have any tips for exceptions? (Inheritence, messages, etc.).
 
Both. I am looking for particular formats for writing XML Documentation and for exception messages (for example if (x < 10) throw new ArgumentException(???)...)
 
Back
Top