Posts Tagged ‘CSharp’

My love affair with Visual Studio: Error Correction

I have been working with Visual Studio for years, and I’ve found a few tricks along the way that make my coding easier. In this blog post I’ll show one of my favourite time savers the Error Correction feature.

When you are writing code for a form or a class as part of a team, or even if you are just starting work on a project which will be made up of multiple classes, you always end up having to reference classes, properties, or methods in your code that haven’t been written yet. So you either have to comment out those calls, add them later, or add stubs so your code will compile. In Visual Studio 2010 they added a neat little feature that will add the stubs for you!

Say I am writing code for a click event handler that will create and populate an instance of a Student object who will be registering for a course. I haven’t created the Student class yet so I see a squiggly under the word student and this little rectangle at the end of the squiggly.

image

Now comes the cool part, I can carefully hover the mouse over the tiny rectangle and a little warning symbol will appear, if I hover just right it will appear with an arrow beside it that I can click on.

ErrorCorrectionOptionSmall

Clicking on that little arrow will bring up a menu of options that will fix the error for me! By the way, if like me, you find using the mouse to bring up the list fiddly, you can use the keyboard to bring up the correction menu by putting the cursor on the word student and hitting CTRL + . that’s CONTROL KEY and a PERIOD.

ErrorCorrectionListSmall

Visual Studio is offering to create a Student class for me, or to define a new type (variable essentially). If I click on Generate ‘Class Student’ I can see a new class appear in Solution Explorer called Student.vb

image

If I open up the Student class I see it has not only created a class, but because my code called a constructor and passed in two variables, it created a constructor method in the class as well that accepts two variables!

image

The code isn’t complete by any means, but it’s enough to get rid of the squiggly on Student in my event handler!

image

Of course now I have squiggly lines under vFirstName and vLastName because I haven’t declared those yet, but if I bring up the Error Correction list for those variables I select Generate field for vFirstName and then Generate field for vLastName and it adds the declarations for me!

image

Sure, it didn’t’ know what data type to make the variables, it’s not perfect, but when I am trying to test something quickly these little Error Correction tools that will generate code stubs for me can be a real time-saver.

This blog also appears on the Canadian Solution Developer Blog

Advertisements

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; }addingNewXMLElementZoomedin

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.

CollapsedCommentsZoomedIn

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

GenerateXMLDocumentationProperty

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 Smile

This blog is also available on the Canadian Solution Developer Blog