How to document the Main method?

Question

Okay, so I've got a .NET console application with it's Main method, contained in a Program class. You know, the usual:

class Program
{
    static void Main(string[] args)
    {
        // Do something spectactular
    }
}

Since I've started using StyleCop and FxCop so rigorously, I've become kind of nit-picky about making sure everything is properly documented.

Then it hit me. I have absolutely no idea how to properly document Program and Program.Main.

I suppose, in the long run, that you could go with the following:

/// <summary>
///     Encapsulates the application's main entry point.
/// </summary>
class Program
{
    /// <summary>
    ///     The application's main entry point.
    /// </summary>
    static void Main(string[] args)
    {
        // Do something spectactular
    }
}

But that seems woefully inadequate (despite the fact that my Main routines always delegate to other classes to do the work).

How do you folks document these things? Is there a recommendation or standard?

Answer 1

Add documentation at the class level that describes what the console program actually does, so it's purpose.

In the Main method, document the required arguments etc., unless if you hand that off, 'main entry point' does suffice.

I tend to hand it off to an instance method in Program called Run(string[] args), so in that case, document the Run method with the arguments/switches options.

The body of my Main() method then simply looks like:

Program prog = new Program();
prog.Run(args);

Answer 2

Don't, just don't. Just look at those 2 samples you created and compare which is more readable?

I'll bet you'll choose the one without comments.

Answer 3

In my humble opinion, it's not worth the trouble to document the main function, especially if you are just going to say "The application's main entry point." If someone doesn't know that Main is the application's main entry point, you don't want them anywhere near your code :-)

If you were to put anything there, you might document what the expected or accepted arguments are, but I think there are better places to document program options (like, a usage function that prints usage, the users manual, a readme file, or elsewhere), since that information is useful not only to developers but also to users of the software.

Answer 4

Documentation is there to add something that's not obvious from the code. And tools are there to help you, not to dictate you what should and should not be documented.

"The application's main entry point" does not add anything, so don't write it.

If there's anything non-obvious like parameters, document this.