Search code examples
asp.net-mvccommentsstylecop

Commenting a ASP.NET MVC Controller


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?


Solution

  • 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.