An excellent and complicated to use code library is inferior to a not so great one that is easy to use. As a developer, I strive to write user friendly libraries. Providing concise, easy to read, and accessible documentation is part of a quality library creation. This can be easily accomplished using Visual Studio.
Visual Studio has a neat feature that auto-generates the documentation section for a class, method, or an interface. By positioning the cursor just above the class declaration or method interface and typing “///” will auto generate comment section that developer needs to fill out.

/// <summary>
/// </summary>
/// <param name="customerNumber" />
/// <returns></returns>
public string GetBillPayAccount(int customerNumber)

When xml documentation file is generated, the comment section will become part of it. In order to enable documentation generation (disabled by default) we need to modify a project setting. Right click on the project, choose properties, then select “Build” tab. At the bottom in the “Output” section check the checkbox “XML documentation file” and in the text box to the right of the checkbox enter the documentation file name.

When the project is built, the documentation file will also be created. This file is also consumed by Visual Studio to provide one of my favorite Visual Studio features, the intellisense. Intellisense provides autocompletion when developer is typing the code. It also provides relevant information (data type, parameter list, access modifier, return type) for variables, functions, and methods. It is provided for .NET languages out of the box and for javascript starting in Visual Studio 2008 version. In order to activate intellisense for a custom built library, the xml documentation file needs to be present in the same folder where the assembly file is located. It is a good practice to keep the assembly files together with their accompanying documentation files and also deliver them together.


Conclusion
Developing my own libraries, I make sure that the code is documented in a concise manner. An easy access to the documentation is accomplished using intellisense. I generate a corresponding documentation file for every assembly. Following these practices have improved my productivity and made programming more enjoyable.

Next week
I will show how to look inside a .NET assembly and how to prevent other people at looking inside your own assembly in “Obfuscation basics” post next week.