By The Way There is Still No Documentation…

A couple of weeks ago I talked about the challenges of finding up to date documentation and showed you how to generate dependency graphs to help you figure out the structure of your code using Visual Studio 2010 Ultimate Edition.

This week I want to show you another useful feature in Visual Studio 2010 to help you generate documentation from existing code. The dependency graphs are great for big picture analysis, which assemblies are referenced and the classes in each assembly, but what if I need a lower level of detail?

Once again Visual Studio 2010 Ultimate Edition comes to the rescue with the sequence diagram generator. Maybe you’ve been asked to investigate an error message received by a user when they click on a particular button. You can just go into the event handler and generate a sequence diagram to determine the method calls from that event handler. This is much simpler than manually walking through the code class by class, method by method. Simply place the cursor in the code editor window, within the method for which you want to generated a sequence diagram and right click. Choose Generate Sequence Diagram from the context menu as shown in Figure 1.

Figure 1 Generating Sequence Diagram

When you select Generate Sequence Diagram you get a window which allows you to control the level of detail you want to include in the sequence diagram.

Figure 2 Generate Sequence Diagram Pop Up Window

Let’s take a quick look at the different options

• Maximum call depth controls how many calls deep you want the sequence diagram to draw. If you have a lot of nested calls and different classes you probably want to increase this from the default value of 3.
• Include calls in Current project will display only calls to methods in the same project as the method you selected
• Include calls in Current Solution will display only calls to methods in the same solution as the method you selected
• Include calls in Solution and external references will display all calls to all methods regardless of the assembly or location where they reside
• Exclude calls to Properties and events will leave out calls to get and set methods for properties or event handlers, unless you suspect the error is in a get or set method, the diagram is usually easier to read without these calls.
• Exclude calls to System namespace will leave out calls to any methods that are part of the System namespace, since most of the time the bugs are in our code, we often exclude these calls, though there are times when seeing System namespace calls can be helpful, for example when debugging localization issues or database connections.
• Exclude calls to Other namespaces allows you to explicitly list namespaces whose calls you want excluded from the diagram, this allows you to focus in on specific sections of code
• Add diagram to current project allows you to save the diagram in your project with a .sequencediagram extension

If I choose OK and generate the sequence diagram with the default values shown in Figure 2, Visual Studio generates the sequence diagram shown in Figure 3.

Figure 3 Default Sequence Diagram

You can see my event handler instantiates a new Student object, and then calls the Save method of the Student class which instantiates an instance of the StudentData class and calls the Add method. This is a very simple example, but shows how quickly you can outline method calls from the event handler. Generating a sequence diagram does not take very long so you can experiment with different settings to get the right level of information for your needs.

So once again, without using any external tools, we have the ability to generate documentation for our undocumented project! You already have Visual Studio, it is so much more than just a code editor! For just a quick sense of how much more it can do, just take a minute to look at the Visual Studio 2010 feature comparison chart. What features are you using? Testing? Database development? Version Control? Build Automation?

Today’s My 5 is related to documentation

5 ways to make your code more readable

1. Do not abbreviate variable names with autocomplete and intellisense features (especially the pascal case intellisense in Visual Studio 2010), you don’t need to keep your variable names 3 characters long anymore!
2. Do not call your variable “id” unless it is REALLY obvious what id is stored in that variable. The number of times I have had to read through code to figure out if id represented a StudentId, CourseId, CategoryId or ClassId, this is one of my pet peeves.
3. Start using LINQ to SQL building T-SQL statements by concatenating strings is really confusing to read and prone to syntax errors like missing spaces or commas, LINQ to SQL is easier to read and debug.
4. Use meaningful parameter names once again the intellisense is a great feature and it works for your methods as well as the built-in methods, so use meaningful parameter names so that anyone calling your method can easily figure out the expected parameter values.
5. Be consistent with casing are you going to use uppercase for constants? pascal casing vs camel casing for public variables. Be consistent and everyone will get immediately recognized the different types of variables from their names alone.