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.