3

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

我应该在控制器上使用什么样式的注释及其可以提供附加值并增加注释有用性的操作？您已经使用了哪些评论？

4

4 回答 4

10

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

于 2010-06-29T14:59:33.503 回答
1

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

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

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

这会一目了然地告诉您按惯例隐藏的所有内容。

摘要评论应该更具体一点：

/// <summary>    
/// Displays a list of customers.    
/// </summary>
于 2010-06-29T15:06:08.840 回答
1

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

于 2010-06-29T15:47:57.917 回答
0

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

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

于 2010-06-29T14:58:52.783 回答