×
Get in touch

Get in touch with Binary

Binary Studio website uses cookies to enhance your browsing experience. By continuing to use our site, you agree to our Privacy Policy and use of cookies.

Learn more more arrow
Agree
Binary Studio 12.05.2009

Applied C# Xml Documentation


The article is devoted to the problems of quality documentation and ways you can cut time on doing this undoubtedly very useful job. You can let the application generate the documentation for you. How? Please read in the article.

Documentation for software applications: quality criteria

Do you write technical documentation for the project? No, because you still think this is a waste of time? As I faced repeatedly with a lack of technical documentation for the project or its poor quality, I decided to conduct some research.

I assumed that:

  • writing technical documentation is a must,
  • documentation process should be as simple as possible,
  • documentation should be complementary to the code, rather than clarify it,
  • it should remain relevant in the process of modernizing the code,
  • and have a readable form, to be structured.

Automatic documentation generation: how to do?

Our department writes in C# using Visual Studio 2005 / 2008 as a development environment that automatically enables us to adopt a ready means of documenting the rich code - XML Documentation. (I’d like to admit to be fair that there exist a lot of document generators - for different platforms and different programming languages, here is a comparative overview of some of them.)

On the Internet, I came across an excellent article of Alan Dean "C# Xml Documentation" which detailed a process of adding xml documentation to the project, as well as a full review of existing standard xml tags with examples of their use. I have reviewed all of these tags, and roughly divided them into three categories: for mandatory, desirable use, and almost unnecessary. And I consciously strive to narrow the range of mandatory and desirable tags. I got the table like this:

 

Mandatory Desirable Unnecessary
Summary Exception, Param, Remarks, See / Seealso All the rest

 

The toolbox has shrunk to 6 tags. And with those remaining need to adhere to the following important rule: «If you can avoid using the tag - do not use it!». Do not clog xml documentation with redundant information – it becomes unreadable, complicates the process of editing, which in turn increases the risk that documentation ceases to be valid. Once again: «If you can avoid using the tag - do not use it!». In addition, the private members of the class do not need comments at all.

1. <Summary>

Often, the only tag used. In the vast majority of cases, this tag is enough to describe appointment of a class / method / field etc. A very important rule is that within the summary there should be written text only. No nested tags! The only exception is, perhaps, tag <para>.

For example, the temptation is great to use inside of a tag <summary> tag <see>, because in the generated documentation tag <see> will be translated into a link. Don’t do this. First, because when you change the class name, link will cease to be valid and the compiler won’t tell you about this, and secondly, because the content of <summary> tag appears in the contextual help in Visual Studio editor and a full class name with all the namespaces will look messy.

Wrong:

 
Right:

 
It is very important to try to withstand the commentary in the same style. All the methods I comment using pattern [step] [key features]:

 
My pattern for the constructors is "Initializes new instance of [...] using [...]:

 
public MailManager(CultureInfo culture)
Comments for the properties I start with keywords “Gets or sets”:

 

2. <Exception>

It is always a pleasure, when the method warns you about what the exceptional situation it can provoke. It is a pity only that a programmer has to populate exceptions list manually - the compiler is not following the relevance of the list. Therefore, use <exception> tag with caution, because provided information may not correspond to reality. With this in mind, I use <exception> tag rarely, only when I am sure that the method will not change frequently.

3. <Param>

Use the tag <param> only when the parameters put forward any special requirements that are worth mentioning.

 

In this example, 2 requirements being put forward - x and y must be nonnegative. Incidentally, in this example usage of tag <exception> is more then appropriate, right?

4. <Remarks>

This tag should be followed by <summary> tag. It is welcoming the use of nested tags <see> and <seealso> in the <remarks> tag. Moreover, if you do not use <see> and <seealso> tags inside <remarks> tag, than whole <remarks> tag is probably is not needed.

5. <See> / <Seealso>

These tags can only be used inside the tag <remarks>. As with the tag <exception> the compiler will not monitor the accuracy of your references, so use the tags <see> and <seealso> very carefully, and preferably do not use them at all.
It is easy to follow a rule - immediately after the definition of some entity (class, method, etc) write a <summary> for it. Sometimes during the process of writing <summary> for a method, I come to the conclusion that this method is not needed. True - if I can not write a <summary> for a method, I do not understand its appointment. This is kind of an early application architecture diagnosing.
I have described only a set of standard tags. But there are tools that can process additional set of commentary tags (xml is extensible). Following markup makes Sandcastle Help File Builder to insert into the resulting document code snippet from the file:
<code lang="cs" source="TestGizmo.cs" region="GizmoClientSample" />

By the way, MSDN was generated using Sandcastle.
In general, writing documentation is like walking on blade’s age (sorry for the pathos) - on the one hand it is bad when documentation is poor, on the other hand it is bad when documentation process hardens application development process. But there always is a golden middle way.

Eugene T.,
.NET team, Binary Studio