Commenting Code

Commenting is an important part of programming. Comments allow your code to be easily readable and maintainable by other team members. Comments are even helpful as a reminder for what a certain bit of code does if you haven't looked at it for two months. Whatever the reason, you should be commenting your code. But, how do we write good comments?

Comments: Too Much or Not Enough?

A common question that beginner programmers ask revolves around how they should comment their code. This is a great question!

In general, I think its best to leave occasional comments that explain what sections of code do. I also leave detailed comments if I am doing anything not immediately obvious. Overall, there is no right answer to how many comments is the 'right' amount. Some people like lots of comments, some people like fewer. As long as there are enough comments for an equally-skilled programmer to figure out what is going on in the code, I think that is enough.

I think right and wrong is best learned through examples:

The following is an example of code that is doing something obscure. There is a lot of math going on with constants, and it isn't immediately clear what the intention of the code should be. Thus, this snippet could probably use at least a single comment at the top describing what this snippet does. I think more than one comment would be too much though:

 for (int i = 0; i < node.NeighborCount; i++)
{
    Rect outboundLinkRect = new Rect(
        node.NodeRect.x + node.NodeRect.width,
        node.NodeRect.y + ((NODE_EDGE_LINK_BUTTON_SIZE + NODE_EDGE_LINK_BUTTON_SPACING) * (i + 2)),
        NODE_EDGE_LINK_BUTTON_SIZE,
        NODE_EDGE_LINK_BUTTON_SIZE
    );

    if (node is DecisionTreeCondition)
    {
        outboundLinkRect = new Rect(
            node.NodeRect.x + node.NodeRect.width,
            node.NodeRect.y + ((NODE_EDGE_LINK_BUTTON_SIZE + NODE_EDGE_LINK_BUTTON_SPACING) * (i + 2)),
            NODE_EDGE_LINK_CONDITIONAL_BUTTON_SIZE,
            NODE_EDGE_LINK_BUTTON_SIZE
        );
    }
}

But, having too many comments in your code can also be problematic because it makes the code hard to read - especially if the comments are redundant. The following is an example of code that has too many comments that don't add anything to the understandability of the code:

public float Average(float[] values)
{
    // if values is equal to null
    if (values == null)
    {
        return 0; // return the average 0
    }

    float average = 0; // Declare a variable called average.
    foreach(float val in values) // For every value in values
    {
        average += val; // increment average by current value
    }
    // at the end, return the average divided by the number of elements
    return average / values.Length; // return the average.
}

Over time, you will develop a commenting style. If working on a team, ensure that your commenting style complements the rest of the team's commenting styles.

The Power of XML Comments

XML Comments are a special feature to Visual Studio. XML Comments are special comments that one places before the definition of properties, classes, interfaces, and methods that define documentation in a structured format that can be read by Visual Studio and other supporting tools.

If code in the project has XML comments, Visual Studio will display those comments in the intellisense autocomplete window. The ability to have the documentation integrated with autocomplete is a massive boon; it is so much faster to have the documentation right there than to switch tabs to look at the method source!

You can even define XML comments for parameters and return types. Your comments will be displayed in the intellisense window. This is so much faster, especially for other team members who might be using your code but not working on its source directly.

Webpage documentation can also be automatically generated from just the source code and its XML Comments using a tool like Doxygen. This is especially useful when writing code in collaboration with lots of people; it is much easier to search documentation for the members of a class than to find the source file in the project and open it. The following is autogenerated documentation for DarkRift2, a 3rd-party Unity networking library.

To auto-generate the template of an XML comment in Visual Studio, just type /// before a property, class, interface, or method, and the editor will create a new XML block comment with all the relevant tags.

See? It's that easy!