Commenting a ASP.NET MVC Controller

Question

I am a big fan of Stylecop and I always follow it guidelines. I also follow the guideline that state that a comment should bring added value to the code and not repeat what the code is doing.

I'm having a bit of trouble following the commenting guidelines concerning an ASP.NET MVC Controller and its related actions: I can't think about the comments to go on an action, nor the controller.

Let's assume the default HomeController and the default Index action, this is the comments I'm using, but I don't feel like they provide any added value.

/// <summary>
/// Provides functionality to the /Home/ route.
/// </summary>
public class HomeController : BaseController
{
    /// <summary>
    /// Displays an index page.
    /// </summary>
    /// <returns>An index page.</returns>
    public ActionResult Index()
    {
        return View();
    }
}

What style of comments should I use on a controller and its actions that would provide added value and increase the usefulness of a comment? What comments have you already used?

Answer 1

That's MVC. The architecture talks for itself, and comments are needed only in more difficult cases.

In this case, the action method returns a ViewResult, which is HTML. This might help specify in the comments for the <returns> section.

Answer 2

Comments have great value on APIs that others are going to consume to explain how to use the various methods and what the expected parameters and return values are. In your own code, I'd prefer that the names of controllers and actions as well as their parameters be self-explanatory or, at least, easily discovered from the code itself. Your code is the best documentation for what it actually does -- it never gets out of sync with itself as comments nearly always do. In the case of controllers/actions the framework itself is almost always the only consumer, so I'd say to save your comments for code that you haven't (yet) been able to refactor into something easily understandable by someone else and skip the comments that no one will ever read anyway.

Answer 3

What I find really useful for controller methods is to put those things in the comments that derive from convention, and are not obvious from looking at the controller method.

For example, I always include a form of the URL that calls the controller method, like this:

// HTTP://mysite.com/mycontroller/myaction/id  <-- Customer ID

This tells you at a glance all of the stuff hidden by convention.

The summary comment should be a bit more specific:

/// <summary>    
/// Displays a list of customers.    
/// </summary>    

Answer 4

If a developer who looks at your code knows asp.net MVC they should understand your simple example. If you comment that code all you'll be doing is giving a tutorial of asp.net MVC