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.
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.
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.