By The Way There is no documentation (yet!)

In the past few weeks I have talked about some tips on how to survive when you inherit code from someone that has no associated documentation. We looked at how to generate dependency graphs, and how to generate sequence diagrams. But sometimes we do make an effort to document our code. If you are going to spend time documenting code you want to ensure that is time well spent.

One of the problems I ran into on occasion was documentation that was created during coding could not be located by the developers down the road when they were supporting the application. As a result, I am a big believer in including code documentation within the code itself. If the documentation is part of the project and the code, then anyone who has access to the code has access to the documentation. This is why even though they have been around for a while, I love XML comments and wanted to remind you of a few tips to make them as easy as possible to work with.

To add XML comments to your project just go to the beginning of the class or method and put three “/” marks on a line then hit enter (C#) or three ‘ single quotes (VB). When you hit Enter you will get a skeleton for XML comments you can fill in

        /// <summary>
        /// 
        /// </summary>
        /// <param name="StudentToAdd"></param>
        /// <returns></returns>
        public string Add(Student StudentToAdd)
        {

The XML skeleton that is generated will be different depending on where you add the XML comments. The skeleton is just a starting point, you can add a number of other elements to your XML documentation as well by just going inside the XML comments and entering a “<” symbol the intellisense will give you a list of elements to choose from as shown in Figure 1

.csharpcode, .csharpcode pre
{
font-size: small;
color: black;
font-family: consolas, “Courier New”, courier, monospace;
background-color: #ffffff;
/*white-space: pre;*/
}
.csharpcode pre { margin: 0em; }
.csharpcode .rem { color: #008000; }
.csharpcode .kwrd { color: #0000ff; }
.csharpcode .str { color: #006080; }
.csharpcode .op { color: #0000c0; }
.csharpcode .preproc { color: #cc6633; }
.csharpcode .asp { background-color: #ffff00; }
.csharpcode .html { color: #800000; }
.csharpcode .attr { color: #ff0000; }
.csharpcode .alt
{
background-color: #f4f4f4;
width: 100%;
margin: 0em;
}
.csharpcode .lnum { color: #606060; }

Figure 1 Adding Additional XML Elements to the Comments

 

You probably want to sit down at the beginning of a project and decide what elements you want to include for different objects such as classes, methods and properties. After doing this you will want to standardize it for your team by modifying the default skeletons. Well good news, if you are a VB developer you can create a document called VBXMLDoc.xml, for instructions on where to find this file and how to edit it, see the MSDN article Recommended XML Tags for Documentation Comments. If you are a CSharp programmer unfortunately for now we don’t have an equivalent file, but you can create code snippets for the different skeletons.

By the time you are finished entering the comments it can start to take up a fair bit of screen space which can be annoying when you already know your way around the code.  You can collapse/expand the comments using the +/- symbols or CTRL+M CTRL+M (if like me, you prefer keyboard shortcuts) as shown in Figure 2.

Figure 2 Collapsing comments

 

So now you have comments in your code, which can be accessed by all programmers who are working on the code in the future, but honestly I can just do that with normal comments and I can use Code Snippets to insert skeletons. So why use the XML comments? there are two great reasons to use the XML comments

You can generate an XML documentation file from your XML Comments

When you build your project you can generate a file that contains the XML comments. This gives you one document which summarizes all your classes and their members that you can make available to other team members. To generate the documentation you can either specify /doc using the command line compiler or if you are building from within Visual Studio go to Project Properties | Build | Output and select XML Documentation file as shown in Figure 3

Figure 3 Setting Build Options to Generate XML Documentation File

 

Generate Help files from XML Comments

You can generate Help files from XML Comments using Sandcastle which is available on CodePlex. Sandcastle will generate Microsoft style help topics by reflecting your assemblies and reading your XML comments. Help files are an often requested by users and can be a tedious task for development teams so why not leverage XML comments to help with documenting your code and generating the help files!

So instead of creating a separate document that contains the documentation for your code, keep it with your code where the next programmer will always be able to find it, and if you are going to take the time to document your code consider getting your comments to do double duty as source information for user help!

Today’s Top 5 is of course related to documenting your code

5 Best Practices for adding comments to code

1. Add comments at all levels – explain the purpose of the class and the methods not just the methods themselves.
2. Tell me something I don’t know – telling me that a method called Insert will do an insert is not very helpful, what will it insert, are their parameters that affect how it will perform the insert
3. Document the exceptions – When I call someone else’s code I really like to know what exceptions may be raised by that method, so please tell me what exceptions my code needs to handle
4. Be professional – as tempting as it may be sometimes to write tongue in cheek comments, it’s always best to take the high road and keep your comments professional
5. Set a standard – define what you will document for each type of object and consider also standardizing the writing style, will it be bullet point, complete sentences, third person, first person, present tense, past tense? This is particularly important if you plan to generate help files from the comments.

Visual Studio, so much more than just a code editor

This blog is also available on the Canadian Solution Developer Blog

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.

This blog is also posted on the Canadian Solution Developer blog

By The Way There Is No Documentation…

Have you ever been asked to make changes or fixes to someone else’s code? Do any of these scenarios sound familiar? A developer leaves the team and now you have to continue with their code. A consulting company develops an application and then your company decides to do the maintenance themselves to save money and now you have to maintain an application built by another team. An application developed years ago now needs updating with new functionality but all the people who originally worked on that application are now elsewhere in the company.

Yup, that’s life as a developer. To be honest I prefer to just build a new application from scratch then try to decipher someone else’s code and ad or fix their functionality. It is not because the other programmers haven’t produced good code, it’s just the extra hurdle of learning how someone else has built an application. To help with this we traditionally add comments to our code and we create documentation that explains the application. Then we starting running short on time, and the users ask for last minute changes that are have to be included. So we put off updating the documentation and focus on heads down coding to meet our deadlines. After the application goes live, there are changes and fixes to the application as well. We open tickets and create change requests and if you add comments or records to keep track of which modules were updated and why. But is the original application documentation kept up to date? All too frequently the answer is no.

So where does that leave a developer who inherits someone else’s code and needs to add an enhancement or bug fix. Well if you have Visual Studio Ultimate 2010, there is hope. When you open Visual Studio Ultimate you see a brand new menu option called Architecture. So when you open up that code in Visual Studio and you find yourself wondering how this application is designed, and you don’t want to spend hours opening up the different classes to see what is called where. Check it out!

Here’s how it works, you open up the Solution containing the code you need to update. You choose Architecture | Generate Dependency Graph | By Assembly.

Figure 1 Generating a Dependency Graph

This will generate a graph that shows you each of your assemblies and assemblies are dependant on each other. This by itself is very useful when you are trying to determine the risk and potential impact of making a change to a particular assembly. It will also help you estimate the effort that will be required to test a change to a particular assembly because you start to get a sense of where the dependencies lie.

 

Figure 2 Sample Dependency Graph By Assembly

As you can see in the dependency graph shown in Figure 2 the Registration project references the Courses assembly. So I know I need to retest parts of the Registration project if I make any changes to the code in the courses assembly.

If you want more information about the classes within the assemblies you can expand each assembly as shown in Figure 3

 

Figure 3 Expanded Assembly Dependency Graph

Unfortunately this view will not show you exactly which class within the assembly references the other classes. If you want that you need to generate a dependency graph by class. Choose Architecture | Generate Dependency Graph | By Class and you get a diagram that shows you each of your classes and the classes they reference in their code.

Figure 4 Class Dependency Graph

You can see in Figure 4, now we have an up to date view of all our classes and their dependencies. This can make it a lot easier to figure out where to find the code we need to update for a fix, or to determine the impact and effort that will be involved in a particular change.

So there you have it, there are other reverse engineering tools out there, but life is simpler if you don’t have to keep launching separate applications to do everything, so make the most out of the tool you have. Visual Studio Rocks!

Today’s My 5 –

5 ways to learn more about Visual Studio 2010 Ultimate

1. Download a free trial and play with it.
2. Read the product description (it does wayyyy more than just let you write code!)
3. Look at the Feature Comparison Chart so you can see what is available in each version of Visual Studio.
4. Check out a video on the Lab Management feature, a little known gem in Visual Studio Ultimate.
5. Check out Modelling projects, UML right in Visual Studio!

And please share your own documentation success or horror stories from your life as a developer on LinkedIn or by commenting on this blog! I am sure I am not the only one to inherit code with out of date or non existent documentation

This blog is also available on the Solution Developer Blog