注释 ASP.NET MVC 控制器答案

【问题标题】：Commenting a ASP.NET MVC Controller注释 ASP.NET MVC 控制器
【发布时间】：2011-03-09 16:25:35
【问题描述】：

我是 Stylecop 的忠实粉丝，我始终遵循它的指导方针。我也遵循这样的指导方针，即注释应该为代码带来附加值，而不是重复代码正在做的事情。

我在遵循有关 ASP.NET MVC 控制器及其相关操作的评论指南时遇到了一些麻烦：我无法考虑 cmet 进行操作，也无法考虑控制器。

让我们假设默认的HomeController 和默认的Index 操作，这是我正在使用的 cmets，但我不觉得它们提供任何附加值。

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

我应该在控制器上使用什么样式的 cmets 以及它的操作，以提供附加值并增加评论的有用性？你已经用过哪些cmets？

【问题讨论】：

标签： asp.net-mvc comments stylecop

【解决方案1】：

评论对于其他人将要使用的 API 具有很大的价值，以解释如何使用各种方法以及预期的参数和返回值是什么。在您自己的代码中，我希望控制器和操作的名称以及它们的参数是不言自明的，或者至少可以从代码本身中轻松发现。你的代码是它实际工作的最佳文档——它永远不会像 cmets 几乎总是做的那样与自身不同步。在控制器/动作的情况下，框架本身几乎总是唯一的消费者，所以我会说将你的 cmets 保存为你还没有（还）能够重构为其他人易于理解的代码并跳过反正没人会读的cmets。

【讨论】：

所以您建议我忽略 Stylecop 生成的有关控制器和操作的警告？
那么CS1591怎么办？
@ChristianGollhardt 如果我打开了 XML cmets 并希望让面向公众的组件具有 cmets - 例如，当将 Swagger 用于 WebAPI 时 - 那么我通常使用 #pragma warning disable 1591 在API 的非公共部分的文件级别。

【解决方案2】：

我发现对控制器方法真正有用的是将这些东西放在从约定派生的 cmets 中，并且从控制器方法中看并不明显。

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

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

这让您一眼就能看出所有按惯例隐藏的东西。

摘要注释应该更具体一点：

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

【讨论】：

【解决方案3】：

如果查看您的代码的开发人员知道 asp.net MVC，他们应该了解您的简单示例。如果您评论该代码，您将要做的就是提供一个 asp.net MVC 教程

【讨论】：

【解决方案4】：

这就是 MVC。架构自己说话，只有在更困难的情况下才需要 cmet。

在这种情况下，action 方法返回一个 ViewResult，它是 HTML。这可能有助于在 cmets 中指定 <returns> 部分。

【讨论】：