Darrell Norton's Blog [MVP]

Sponsors

The Lounge

Wicked Cool Jobs

News

  • Darrell Norton pic

    MVP logo

    View Darrell Norton's profile on LinkedIn

    Currently Reading:

    weewar.com

Advertisement

Images in this post missing? We recently lost them in a site migration. We're working to restore these as you read this. Should you need an image in an emergency, please contact us at imagehelp@codebetter.com
XML Code Commenting in .NET

Steve said he wonders if XML code commenting violates the DRY principle.  Alan (and others) respond saying that XML comments should only be used to convey the intention of the code to an end user.

Taking this to its logical extreme, XML comments should only be used on the public interface (public methods, class constructors, properties, etc.).  Is this a statement we can live with?  Well, you can no longer crank up the warning level in VS.NET, because it does not differentiate between public and private methods missing comments.  That is a minor implementation detail, but should be noted as something where a manual process or custom software program will have to fill the gap.

And conversely, you should not use XML comments on private or (protected methods in a sealed class) or properties or unit tests.  If you are using something like TestDox, you can have the method name state the intention of the code.  Then there is no duplication and you still can generate code comments.  This would work with private visibility methods and properties, as long as the appropriate level of discipline was in place.  Updating methods would be slightly harder, but since anything affected by method name changes will be local, this is not too difficult. 

If this sounds ok to you, then great.  Just be sure to realize what you are getting yourself into.


Posted Sun, Oct 5 2003 8:51 PM by Darrell Norton

[Advertisement]

Devlicio.us