XML Documentation...

[IceAzul]

Does anyone have any tips on how the descriptions should be formed? Is there some sort of guildeline on how to write the documentation?

[mskeel]

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.

[Nerseus]

Consider your audience and try to write the documentation for them.

 

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

[IngisKahn]

Ghostdoc: Wow, great tool.

[IceAzul]

Just one more question (there is a theme here), does anyone have any tips for exceptions? (Inheritence, messages, etc.).

[PlausiblyDamp]

Do you mean tips on documenting them or just tips in general?

[IceAzul]

Both. I am looking for particular formats for writing XML Documentation and for exception messages (for example if (x < 10) throw new ArgumentException(???)...)