#913 – How to Document that a Method Can Throw an Exception

You can use XML Documentation to document the fact that a method can throw an exception.  You use the Exception tag to indicate the type of exception that can be thrown.  You can also provide a comment related to the exception, which will show up in an XML Documentation file that you generate.

        /// <summary>
        /// Print somebody's name
        /// </summary>
        /// <param name="name">Name to be printed</param>
        /// <exception cref="ApplicationException">Will throw exception if name is Mortimer</exception>
        /// <exception cref="JustBecauseException">I throw this exception on Tuesdays</exception>
        static void PrintMyName(string name)
        {
            if (name.ToLower().Equals("mortimer"))
                throw new ApplicationException("I don't like the name Mortimer");

            if (DateTime.Now.DayOfWeek == DayOfWeek.Tuesday)
                throw new JustBecauseException("Tuesday is my day off");

            Console.WriteLine(string.Format("Your name is {0}", name));
        }

Intellisense will now include a list of the exceptions that might be thrown, when displaying the method’s name.
913-001

 

If you generate a XML Documentation file, it will also include this information.

913-002

Advertisements

#912 – Intellisense Can Show Exceptions that a Method Might Throw

In some cases, when the Intellisense function within Visual Studio shows you information about a method that you are going to call, it will also list potential exceptions that the method might throw.

In the example below, we see that the Matrix.Invert method can throw an exception of type InvalidOperationException.

912-001

 

It’s not the case that every single method that you might call in the Base Class Library (BCL) will provide this information.  Some methods will list the exceptions that they might throw, but many will not.

#770 – Use Intellisense to Get List of Methods to Override

In a derived class, you can override a member of the base class if it’s declared as virtual.  In Visual Studio, the Intellisense feature can help you to discover the methods that can be overridden.

Suppose that we have the following definition for Dog:

    public class Dog
    {
        public virtual string Prop1 { get; set; }
        public string Prop2 { get; set; }

        public virtual void Method1()
        {
            Console.WriteLine("Dog.Method1");
        }

        public void Method2()
        {
            Console.WriteLine("Dog.Method2");
        }
    }

Now when we are adding code to a child class of Dog, we can just enter the keyword override, followed by a space, to see a list of candidate members that can be overridden.

770-001

To add the code for one of these members, just use the down arrow to select the method and then press TAB.  The body of the method will be generated for you.

770-002

#691 – Use the this Keyword to Trigger Intellisense

Another use of the this keyword, which refers to the current instance of a class, is to trigger Intellisense in Visual Studio so that you can  see a list of members in the class.

For example, let’s say that you’re writing some code for the Bark method in a Dog class.  You want to call another method in the Dog class, but you can’t remember its name.  You can just type this and a period (.).  After typing the period, an Intellisense window will pop up to show you the members in the Dog class.

You can then select the method that you want to call and Intellisense will remind you of what parameters are required.

#595 – Intellisense Shows Method Overloads

When you overload a method, you’re creating multiple methods with the same name, but a different number of parameters, or parameters of different types.  At compile-time, the compiler will automatically call the correct method.

Visual Studio can help with entering parameter values.  When you enter the name of a method, Intellisense shows you a list of available methods with that name.

Let’s say that we have three different versions of a Dog.Bark method.  After typing “Bark” and the opening parenthesis “(“, Intellisense will indicate that there are three versions of the method available and provide information about the first version.

At this point, you can press the up/down arrow keys to cycle through the three different methods.

Notice that Intellisense does the following:

  • Indicates in bold the next parameter that you should enter
  • Lists a description of the method, if one is available
  • Provides a description of the next parameter

#591 – How Optional Parameters Look with Intellisense

When you’re working in Visual Studio and you start typing in the name of a method, Intellisense will show you any optional parameters that the method has.

In the example below, we’ve started entering code to create a new instance of a Dog object.  Intellisense shows us a list of the optional parameters that are defined for the constructor.

#439 – Use Visual Studio to Implement an Interface

You can use smart tags in Visual Studio to quickly implement an interface for a class.

For example, let’s say that you want to add code to the Cow class to implement the IMoo interface.  You start by updating the class declaration to derive from IMoo.

If you now hover over the little underline under IMoo, you’ll see a smart tag.

If you click on the smart tag, you’ll see two options.

Click on “Implement interface ‘iMoo’ “.  Empty implementations of all of the interface’s members will be automatically added to the class.  (Note that the methods throw NotImplementedException exceptions by default).