On this page.... RSS 2.0 | Atom 1.0 | CDF
# Monday, November 8, 2004

I've recently come up against something of a dilemma (again) in terms of best practices when using C#'s XML comments feature.  What has me undecided is what the best balance is between inline comments and the use of external files as sources for documentation.

One of the things I like about XML commenting is that it allows you to provide inline documentation with your code while, at the same time, generating the handy XML file that VS uses to provide enhanced Intellisense and, consequently, being able to use that file with NDoc to produce very nice reference documentation (they've got a new version, 1.3, in Beta 2, by the way).

The dilemma is particularly acute in cases where you have overloads of a method and you have a fairly large amount of comments that you want to be visible in the reference documentation for each overload.  And really, the problem extends to any case where you have a large amount of comments for a particular entity in your code. 

Since C#'s XML comments allows the use of include files to generate the final <assemblyName>.xml file, I like to maximize reuse by storing common elements (such as remarks) in an XML include file for overloaded members.  Plus, when you have a lot of text or, worse, code samples, it is easier to create and maintain in an external file (so you don't have to have the initial /// on every line).

The problem is that using an external file eliminates the inline aspect that I also like (as the comments are actually stored in another file).  For now, the best solution I've come up with is to keep the overload-specific summary and all of the parameter comments inline but keep common and large comments in an external file.  Yes, this does mean a small amount of duplication, but it is limited and still provides some amount of inline documentation.

Ideally, it'd be nice if the IDE had a feature to “Show Included Comments” so that anywhere you use the include file option, it would allow you to either display (inline) the included comments or at least jump to that location in the external documentation file (I'd prefer the former).  Maybe the VS team could consider this or, if not, maybe the folks at CodeRush could do it.

In the meantime, I'd love to hear what other people are doing to address this dilemma.

Monday, November 8, 2004 12:10:10 PM (Eastern Standard Time, UTC-05:00)  #    Disclaimer  |  Comments [2]  | 
Wednesday, November 24, 2004 1:19:11 PM (Eastern Standard Time, UTC-05:00)
Nit pick (since we're on the subject of contractions not of the child bearing kind):

>they've got a new version

they've got?

they have got?

Maybe just "they have", or perhaps "there is" which has more agreement with the predicate.

Wednesday, November 24, 2004 3:24:18 PM (Eastern Standard Time, UTC-05:00)
They've got is a colloquialism and, in my estimation, is perfectly acceptable for this medium.
Comments are closed.

The opinions expressed herein are solely my own personal opinions, founded or unfounded, rational or not, and you can quote me on that.

Thanks to the good folks at dasBlog!

Copyright © 2019 J. Ambrose Little