C# Comment Program 1

You want to see how comments in C# programs affect the resulting program's binary code and its execution speed. Some programming languages, even common interpreted ones, have been affected in some way by comments in the program text, but C# is a compiled language where comments do not affect the executable. Here we demonstrate through benchmarking to what extent comments affect the execution of C# programs, and then further explore compiler technologies related to commenting and more about comments.

=== Benchmark results for uncommented and commented methods (C#) ===

Increment:             0.331 ms (uncommented release)
IncrementWithComments: 0.330 ms (commented release)

Increment:             0.308 ms (uncommented debug, fewer iterations)
IncrementWithComments: 0.308 ms (commented release, fewer iterations)

Using comments in methods

Initially here we see program text that defines two methods that do the exact same thing. The two methods, Increment and IncrementWithComments, are identical except that the first has no comments and the second has almost 20 lines of comments on it. By testing these two methods, we can show what effect comments in methods has on execution performance for the C# language.

--- Program that has uncommented and comment methods (C#) ---

class Program
{
    static void Increment()
    {
        int value = 0;
        for (int i = 0; i < 100000; i++)
        {
            for (int j = 0; j < 10; j++)
            {
                value++;
            }
        }
        _field = value;
    }

    /// <summary>
    /// This version of the increment method has many comments.
    /// </summary>
    static void IncrementWithComments()
    {
        // -----
        // Local variable in variable slot that is incremented.
        // -----
        int value = 0;
        // -----
        // Loop through the first one-hundred thousand numbers.
        // -----
        for (int i = 0; i < 100000; i++)
        {
            // -----
            // Nested loop through first ten numbers.
            // -----
            for (int j = 0; j < 10; j++)
            {
                // -----
                // Increment the variable once.
                // -----
                value++;
            }
        }
        // -----
        // Store local variable's value in static field.
        // -----
        _field = value;
    }

    static int _field;

    static void Main()
    {
        Increment();
        IncrementWithComments();
    }
}

Increment method versus IncrementWithComments method. The program text contains three methods: two methods that increment a local variable and the Main entry point that calls those methods. The key point here is that the first method, Increment, contains no comments in the program text. The second method, IncrementWithComments, has the exact same logic but has almost 20 lines of comments in it.

XML comments and // comment style. The method IncrementWithComments demonstrates two different kinds of comments. First, it shows XML-style comments at the level of the method signature. XML comments have three / characters (///) at their start. They can be used to output more detailed documentation on class data. Note that XML comments are not useful for local variables inside methods.

Benchmark

Here we describe the results of the benchmark taken in this article. The two methods shown in the program text, Increment and IncrementWithComments, were tested against each other in loops. To improve the quality of the results, the methods were called once before the timed loops to ensure they were JIT compiled. The benchmark was executed in DEBUG mode and RELEASE mode using the .NET Framework 3.5 SP1. The times measured were almost exactly the same for both the uncommented and commented versions of the methods. This shows that the 18 lines of comments on or in the IncrementWithComments method had no performance effect.

Compiler phases

Here we discuss how compilers are logically organized into phases and how these phases are grouped into passes. Early in the compilation cycle, compilers use a lexical parser that converts the program text into a series of lexemes, which is compiler-terminology for program "words". At this point, the compiler can remove all lines beginning with the // characters and text between the /* and */ delimiters. Because of this phase, the compiled DLL from the C# code contains no trace of the comments and the executable source is identical in both methods.

Commenting guide

In this section, we note some practical tips for adding comments to your C# programs and programs in other languages. It is usually recommended to describe at the level of intent, not the level of implementation. So you can comment on what the code is supposed to do, not how it actually does that. You can focus on "why" and "what" and not on "how". The book Code Complete by Steve McConnell contains a large chapter on commenting strategies.

(See Code Complete [Book Review].)

Using Reflector on DLLs

Here we note a more advanced way you can see how the C# compiler translates programs into the intermediate language of the .NET Framework. There is a tool called Reflector that actually can read in the compiled DLL or EXE of your program and represent the abstract binary format in C# code. This gives you the ability to read the C# code from your compiled DLL. This code will have no comments or local variable names because these were removed.

Summary

Here we looked how comments in the C# programming language affect the resulting executable sources and the intermediate language. We showed that comments have no effect on the performance of C# programs. We reviewed some compiler concepts related to lexical parsers and then noted some issues related to commenting style and how you can disassemble compiled programs to better understand the compiler's output.

(Do not copy this page.)