Комментирование контроллера ASP.NET MVC

Question

Я большой поклонник Stylecop и всегда следую его указаниям.Я также следую указаниям, в которых говорится, что комментарий должен принести дополнительную ценность коду, а не повторять то, что делает код.

У меня возникли некоторые проблемы с соблюдением рекомендаций по комментированию ASP.NET MVCКонтроллер и связанные с ним действия: я не могу думать ни о комментариях к действию, ни о контроллере.

Давайте предположим действие по умолчанию HomeController и действие по умолчанию Index, это комментарии, которые яЯ использую, но я не чувствую, что они предоставляют какую-либо дополнительную ценность.

/// <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();
    }
}

Какой стиль комментариев я должен использовать на контроллере и его действиях, которые обеспечат дополнительную ценность и увеличат полезностькомментарий?Какие комментарии вы уже использовали?

Answer 1

Комментарии имеют большое значение для API, которые другие будут использовать, чтобы объяснить, как использовать различные методы и каковы ожидаемые параметры и возвращаемые значения. В вашем собственном коде я бы предпочел, чтобы имена контроллеров и действий, а также их параметры были понятны или, по крайней мере, легко обнаруживались из самого кода. Ваш код - лучшая документация для того, что он на самом деле делает - он никогда не синхронизируется с самим собой, как комментарии почти всегда. В случае с контроллерами / действиями сама инфраструктура почти всегда является единственным потребителем, поэтому я бы сказал, чтобы сохранить ваши комментарии для кода, который вы (пока) не смогли преобразовать во что-то, что кто-то может легко понять, и пропустить комментарии, которые никто никогда не прочтет.

Answer 2

Если разработчик, который просматривает ваш код, знает asp.net MVC, он должен понять ваш простой пример.Если вы прокомментируете этот код, все, что вы будете делать, это дать учебник asp.net MVC

Answer 3

То, что я считаю действительно полезным для методов контроллера, - это помещать те вещи в комментарии, которые вытекают из соглашения, и которые не очевидны из рассмотрения метода контроллера.

Например, я всегда включаю форму URL-адреса, который вызывает метод контроллера, например:

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

Это говорит вам сразу обо всех вещах, спрятанных по соглашению.

Краткий комментарий должен быть более конкретным:

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

Answer 4

Это MVC.Архитектура говорит сама за себя, и комментарии нужны только в более сложных случаях.

В этом случае метод действия возвращает ViewResult, который является HTML.Это может помочь указать в комментариях к разделу <returns>.