Ease the burden of commenting your code

Usually when you mention "adding comments to your code" or "make sure you document it", it gets pretty ugly and the security guards are called in to restore order. Okay, maybe not that intense but you would have to agree that it's not a fun task.

If you are building the code from scratch, it's relatively easy to maintain those comments as you go. However, when you haven't done it in the past - or are given a suite of products to maintain and it was never done, it could be pretty tedious.

Say I have a method:

public static void switchRoleToAdmin()
{
   //Code to switch role to admin
}

Adding a comment to this one is pretty easy. There are no parameters, no return objects, etc. It would look something like this:

/// <summary>
/// Switches the role to admin.
/// </summary>
public static void switchRoleToAdmin()
{
   //Code to switch role to admin
}

Not bad. However, it can get pretty scary when there are several parameters and a return value.

Example:

public static string addPayment(Enum payeeType, string payeeName, decimal amount, string currency, string notes, string commentsToPayee, string description, string invoiceNumber, DateTime? invoiceDate, DateTime? scheduledPayDate)
{
   //code to add payment.  In this case, it returns a payment number.
}

Adding code to this method is pretty tedious and to add value to the method would really take some time. Well, in doing this exercise I found a tool called GhostDoc. (http://submain.com/products/ghostdoc.aspx) I am sure there are many out there, but it integrates nice with Visual Studio and it seems to work fine.

On this method, I just right click on the method declaration and select "Document this" from the context menu. Within an instant, I get this output:

        /// <summary>
        /// Adds the payment.
        /// </summary>
        /// <param name="payeeType">Type of the payee.</param>
        /// <param name="payeeName">Name of the payee.</param>
        /// <param name="amount">The amount.</param>
        /// <param name="currency">The currency.</param>
        /// <param name="notes">The notes.</param>
        /// <param name="commentsToPayee">The comments to payee.</param>
        /// <param name="description">The description.</param>
        /// <param name="invoiceNumber">The invoice number.</param>
        /// <param name="invoiceDate">The invoice date.</param>
        /// <param name="scheduledPayDate">The scheduled pay date.</param>
        /// <returns></returns>
        public static string addPayment(Enum payeeType, string payeeName, decimal amount, string currency, string notes, string commentsToPayee, string description, string invoiceNumber, DateTime? invoiceDate, DateTime? scheduledPayDate)
        {
            //code to add payment.  In this case, it returns a payment number.
        }

Obviously, there isn't too much additional detail to gather from this, but it sure saved me a ton of time writing all of that. Some tools will create the xml structure, but you still have to enter the details of each parameter. Now, I can add additional detail to the summary, or maybe add specifics to the returns node. Either way, it's easy to add those and saves me a ton of time.