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

在控制器及其操作中，我应该使用什么样的评论才能提供附加价值并增加评论的实用性？您已经使用过哪些评论？

- Pierre-Alain Vigeant

Answer 1

注释对于其他人去使用的API具有极大价值，可以解释如何使用各种方法以及预期参数和返回值。在您自己的代码中，我更希望控制器和操作的名称以及它们的参数是自说明的，或者至少可以从代码本身中轻松发现。您的代码是最好的文档，用于实际执行的功能--与注释几乎总是不同步。在控制器/操作的情况下，框架本身几乎总是唯一的消费者，因此我建议将注释保存在尚未能够重构为易于他人理解的内容的代码上，并跳过任何人都不会阅读的注释。

- tvanfosson

---

那么您建议我忽略 Stylecop 关于控制器和操作的警告？ - Pierre-Alain Vigeant

那么CS1591应该怎么处理呢？ - Christian Gollhardt

如果我开启了XML注释并想让面向公众的组件有注释 - 例如，在使用Swagger进行WebAPI时 - 我通常会在API的非公共部分中在文件级别上使用#pragma warning disable 1591来抑制CS1591。 - tvanfosson

Answer 2

我认为对控制器方法非常有用的是在注释中放置那些来自惯例且通过查看控制器方法不明显的内容。

例如，我总是包括调用控制器方法的URL形式，如下所示：

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

这可以一眼看出所有按照惯例隐藏的内容。

摘要注释应该更加具体：

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

- Robert Harvey

Answer 3

如果一个开发人员看到你的代码并了解asp.net MVC，他们应该能够理解你的简单示例。如果你对那段代码进行注释，你只是在给asp.net MVC提供教程。

- BritishDeveloper

Answer 4

这就是MVC（模型-视图-控制器）。架构本身已经足够说明，只有在更困难的情况下才需要注释。

在这种情况下，动作方法返回一个ViewResult，它是HTML格式的。这可能有助于在<returns>部分的注释中进行说明。

- Alex