By The Way There is no documentation (yet!)

Artikel
08/11/2011

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

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

Add comments at all levels - explain the purpose of the class and the methods not just the methods themselves.
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
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
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
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 Smile

Comments

Anonymous
August 13, 2011
Nice article. Another key thing to keep in mind:It always helps to provide meaningful usage guidelines for methods and parameters. It helps the client application to see these descriptions in intellisense view.

Dela via