C# - Self documenting code
-
Hi Everybody - Happy Easter, have a peaceful weekend... I'd like to ask, to what extent do you use the XML tags in your code (such as summary etc.) I wonder if you could point me to some code that you consider "model" in its illustration of good practice. Also, do you use any additional tools. I have a developed an architecture that I consider elegant and simple to use, but to maintain it, it would require good documentation. I would welcome any thoughts and guidance so I can get past my basic use of summary and parameter tags. Many thanks. Nursey
-
Hi Everybody - Happy Easter, have a peaceful weekend... I'd like to ask, to what extent do you use the XML tags in your code (such as summary etc.) I wonder if you could point me to some code that you consider "model" in its illustration of good practice. Also, do you use any additional tools. I have a developed an architecture that I consider elegant and simple to use, but to maintain it, it would require good documentation. I would welcome any thoughts and guidance so I can get past my basic use of summary and parameter tags. Many thanks. Nursey
At least document everything public and protected, anything which can be seen by other code. Use all relevent XML tags. This includes, obviously, the
<summary>. If your method has parameters, then use the<param>tags. If you return values, use the<returns>tag. If you explicitly throw an exception or let one slide that you want to make sure developers know is possible, use the<exception>tags. Basically, use any tags that are relevent to the to member. If you want to provide more information about something, then use the<remarks>and/or<example>tags. For a great and free documentation compiler, see NDoc[^]. I've had the pleasure of working on it and I know this product is stable. Just look at the huge list of clients, including Microsoft. It can generate many formats like HTML Help 1 (ex: VS6 docs) and 2 (ex: VS7+ docs). It looks just like the current VS.NET / MSDN documentation as well. For larger products in a corporate environment, you might consider abstracting all comments away to separate files. Then use the<include>tag to specify an XPath expression that imports the documentation. This seems to be what Microsoft does since many members - especially overloaded methods - share the same content for various sections.Microsoft MVP, Visual C# My Articles