Question

Closed. This question is opinion-based. It is not currently accepting answers.

Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.

Closed 5 years ago.

Improve this 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

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 2

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.

Answer 3

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 4

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.

友情链接