Code Documentation in .NET
page 1 of 5
Published: 18 Jul 2005
Unedited - Community Contributed
Abstract
Documenting your code in .NET is much easier than you might expect. In this article, Steven Swafford discusses the XML documentation tags recommended by Microsoft, and shows how to put these tags to use. By taking the time to document your code, not only will you and others be able to clearly understand the code and utilize features such as IntelliSense, you will also be able to employ third-party tools such as NDoc to generate professional-looking MSDN-style documentation. This article also looks at the value of well-documented code.
by Steven Swafford
Feedback
Average Rating: 
Views (Total / Last 10 Days): 91477/ 98

Introduction

As a developer, I myself have a very strong opinion that all code that is written should be documented. Documentation should always be foremost in your thought process. Why, you may ask? Well, let me explain. Have you ever been in a position where you were hired for a project, and there was absolutely no documentation whatsoever for anything that was written? I know from firsthand experience the headache that this can cause no matter which programming language is used. For example, what if you were tasked with changing the discount price on an item a consumer may purchase, and you then open the code only to find an in-depth process to calculate the discount, and there was not a single comment in the code? In this type of scenario, you must track down an individual who can provide the specific business rules for this process before you can begin to understand what the code is doing.

Documentation is a straightforward and simple process for C# and VB.NET. While C# XML documentation is supported in Visual Studio 2003 and above, developers who code in VB.NET have had to turn to alternative means when it came to documentation. While there are, in fact, a variety of products on the market that assist in overcoming this problem, the good news is that Visual Studio 2005 now supports VB.NET XML documentation inherently. I am sure that this will be a much-welcomed addition for VB.NET developers.

The goal of this article is to raise the awareness of code documentation and the importance of well-written documentation. I will also cover the specifics of writing documentation, and explain the benefits that you and other developers will experience from such documentation. I will not provide in-depth code examples; rather, I hope to stress the importance and benefits of documentation.


View Entire Article

User Comments

No comments posted yet.






Community Advice: ASP | SQL | XML | Regular Expressions | Windows


©Copyright 1998-2014 ASPAlliance.com  |  Page Processed at 4/23/2014 4:01:47 AM  AspAlliance Recent Articles RSS Feed
About ASPAlliance | Newsgroups | Advertise | Authors | Email Lists | Feedback | Link To Us | Privacy | Search