Documenting Code in Visual Studio.Net - Part I

After writing that incredible .Net program comes the questions about support and documentation. Some people like Visio and other pictorial views of the documentation. I like external tools too...but I have always been an advocate of keeping the code and documentation together. What if the code changes? How do you update the documentation and keep everything current?

And then there is a question of style and standards. How do you enforce documentation standards for multiple developers...assuming you can get them to document in the first place. And what about the clutter that happens when people start writing all the comments within the code?

Automated Documentation in VS.Net
Luckily, Visual Studio.Net creates a standard method for documenting code. It creates a standard that is easy to stick to and I believe it even promotes more documentation*. The way to document code is to go to a class or method definition and type /// immediately above the definition of choice. VS.Net will then automatically add some commented XML to the file in question. If you are writing comments for a method with arguments, VS.Net will also creates for the arguments. If the method returns a value, an XML tag will be created for the XML value.

For example, let's say you have the following method:

public DataTable SelectInner(string TableName, string RelationName) {...}

Typing 3 slashes above the call, will automatically produce the following XML:

/// <summary>
///
/// </summary>
/// <param name="TableName"></param>
/// <param name="RelationName"></param>
/// <returns></returns>

To document the method, simply type your comments within the tags. The 'summary' tag defines the method, the 'param' tags define each parameter, and the 'returns' tag defines the return value. It's simple and give the user a quick place to define all the key inputs and outputs of the method.

Documenting code that is internal to the method is similar, but more free form. Simply type /// above the line or variable in question. VS.Net does not create fields, but these comments become more important in the next step, which is generating human readable documentation from the source files.

MSDN has documented their recognized tags. For further reading, check out this article, entitled 'XML Comments Let You Build Documentation Directly From Your Visual Studio .NET Source Files'.

-------------
* This posting applies to Visual C#/Visual C++ only. While there is theoretical support for J# and VB.Net, I have not personally tested it and therefore cannot vouch for how well it works.

Deploying files with an Install project

Microsoft Visual Studio Pro provides a suite of tools for deploying files and creating a folder structure at install. At this point, I am not an expert at the deployment (see other deployment postings), but following is how to deploy files:

1. Right-click on the Install/Deployment package
2. Choose View > File System
3. Add files and folders. They will be added to the install structure defined in the deployment package.

Deploying files with a ClickOnce Project

Deploying files with a ClickOnce Project

The switch to deploying a Windows Services has got me thinking about how to deploy files and settings with the application. So, today I have been exploring the various ways to deploy data files with C# projects. Following are the ways I have discovered:

--------------------------------------------------
Project Properties > Resources
Resources are files that can be compile directly into the executable. I would recommend this for XSD or XML files that will not be edited after deployment.

How to Reference: [Namespace].Resources.Resource Name;

Pros: Easy to reference and deploy. In testing, XML files were rendered as strings and easily loaded into memory for easy parsing.
Cons: I do not believe that resources can be edited after deployment. They are compiled directly into the executable.
--------------------------------------------------
Project Properties > Settings
This looks like the best place to store editable data. These settings are deployed in the .config file stored in the application directory with the executable. The file is an XML file - change the appropriate setting. It looks like settings can be set to simple or complex types and can be changed programmatically at run time. They can also be changed at run time.

How to reference: [Namespace].Properties.Settings.Default[string id];

Pros: It is easy to change the settings once the application is deployed.
Cons: The format my take complex types, but I'm not sure if it is serialized in a human readable format. Strings are easily editable provided you can find the .config file on the hard drive.

--------------------------------------------------
Data Files
Data files are added directly to the project. They are deployed in their original state with each install.

How to reference: You need to check to see if the system is in a deployed state. If yes, the look in the ApplicationDeployment.CurrentDeployment.DataDirecrory. From an editing perspective, the files can be edited at runtime.

Pros: The file makes the transition to the deployed computer completely intact. Coding for the local location is not difficult.
Cons: The install directory for the data file is complex and contains a guid. If there is more than one version of the application installed on the machine, it may be difficult, if not impossible, to find and update the correct file. The coding for checking the deployed stated is a little obtuse, but that could be solved with a quick object.

Regular Expressions and Like Statement

There is a new requirement for this application to be able to parse numbers embedded in file names. One issue is that C# DataTables do not allow for complex, regular expression searches in fields. That means that I will have to create on the fly regular expressions, query my local files database and then run a post process on the remaining records to see if more than one file comes up.

The query process will be as follows:

1. When loading hooks into the table, replace [snam] with the SNAM
2. Create a boolean value in the table to indicate if the hook has a [n] wildcard in it
3. Query the files table with the first [n] in the hook as the */% wildcard
4. Pass the records to a function with the hook. The function returns the number of records found.
5. Build a regular expression based on the string. Replace '[n]' with '[0-9]+'
6. Cycle through the array. If a match is found, increment the match.
7. Return the array back to the calling function for processing.

How to use the Settings class in C# - The Code Project - C# Programming

This article updates my knowledge of application settings in Visual Studio. The important points are:

* Settings can be directly accessed using early binding. The way to access it remains:

1. Set the reference to the proper namespace:
using [Assembly Name].Properties;
2. Refer to the property (substitute property name):
Settings.Default.PropertyName
3. Save the property:
Settings.Default.Save();

* Settings as the Application level are read only. Settings at the User level are read/write.