One of the most valued practices in software development is brevity.  Writing code is bad.  When you write code you create bugs, and creating bugs is bad.  The solution?  Don’t write much code.  Commenting your code however, has traditionally been seen as a “good thing”.  So much so that most modern programming environments make some provision for document generation and offer style-guidelines for commenting your code.

I believe, however, that excessive commenting is actually an anti-pattern and should treated with caution, and as far as possible, avoided.  I’m going to illustrate my point with a (somewhat contrived, but in no way unusual or outlandish) example.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace XmlDocumentationAntiPattern
{
    /// <summary>
    /// XmlCommentHell
    /// </summary>
    /// <example>var xmlCommentHell = new XmlCommentHell</example>
    public class XmlCommentHell
    {
        /// <summary>
        /// Description
        /// </summary>
        /// <remarks>String description of XmlCommentHell.</remarks>
        /// <example>instance.Description = "some description";</example>
        public string Description { get; set; }

        /// <summary>
        /// XmlCommentHell ctor
        /// </summary>
        /// <param name="description">Description string</param>
        public XmlCommentHell(string description)
        {
            // Assign description
            Description = description;
        }

        /// <summary>
        /// Gets the description property, but in reverse!
        /// </summary>
        /// <returns>Reversed description</returns>
        public string GetReversedDescription()
        {
            return Description.Reverse().ToString();
        }
    }
}

The context of this example is C# but similarly applies in other programming languages.

If you find yourself engaging in XML comments like the above example, I really believe “you’re doing it wrong”.  Why?

• Reduced code readability
  
  The Xml comment clutter in the code above actually reduces it’s usefulness.  The code now takes three times as much screen real estate to maintain and understand.
  
• Low signal to noise ratio - too many characters that add no value
  
  When you’re maintaining systems however large, the act of actually writing code takes time and adds maintenance overhead.  Past the visual unpleasantness the amount of mark up required to document relatively simple methods actually reduces the codes utility.  Only ever type ANYTHING in your IDE if it adds value.
  
• Incredibly obvious comments
  
  There’s a wonderful quote to the tune of “always pretend that the person that’s going to maintain your code is an axe wielding manic who knows where you live”.  I’d like to extend that by adding “so don’t insult their intelligence”.  There are few things I find as frustrating as reading comments that not only add no value but also make me feel like I’ve wasted a tiny piece of my life reading them.  Don’t waste your time or mine.
  
• Violating the DRY principle
  
  The DRY principle is very well agreed upon in software development.  Don’t repeat yourself.  If your XML comments just repeat your method signatures, you’re not only repeating yourself (and thus wasting time) but you’re leaving yourself open to a maintained nightmare as the code changes and the comments are left unchanged leading to confusion and misinformation.
  
• Possible misuse – the generation of utterly useless documentation
  
  When I see projects documented in this way I often joke that someone should run Sandcastle or javaDoc over the code to gain some tangible value in the form of MSDN-esq documentation.  I’m actually wrong.  This is a terrible idea.  Pop quiz time!  What’s worse than tedious documentation that adds no value?  Tonnes of hyperlinked documentation that adds no value!  Think of the poor developer wasting minutes to hours searching for the value in generated documentation before painfully realising that there’s none to be had.
  

I occasionally get met with some resistance when I state my opinion on this for a couple of reasons.  People often argue that they do it for the sake of intellisense and IDE tooling, that they do it for generated documentation or just out of habit.  I feel like these are all dangerous reasons.

Firstly, if you’re generating documentation for documentations sake, you’re either trying to please some form of middle management that doesn’t understand what documentation really exists for (hint: to help developers develop), or you’re wasting time.

Secondly, if you’re documenting methods for intellisense you’re probably missing the point.  See, intellisense and other IDE self-help mechanisms are very good; they’ll display method signatures and method names with minimal fuss, any extra comments you glue on top of every method will either clutter your GUI, or become ignored white noise, potentially leading to that one important comment going ignored as your developers slowly desensitise themselves to reading the human generated “auto-doc” garbage.

Finally, if you find that you need to cover your methods in comments because they legitimately don’t make too much sense at a glance then you’re falling foul of a different problem: you have code that’s not legible maintainable and clear.  In this case you’d be far better served by ensuring your methods are named well, take logical parameters and have single clearly defined purposes.  In my experience, whenever somebody says that they need to comment their methods because the method is unclear, they really should be refactoring, not documenting.

Please DON’T bury your code in comments, just keep it all readable ok?