asp.net-mvc - 注释 ASP.NET MVC Controller

Question

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

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

让我们假设默认 HomeController和默认 Index行动，这是我正在使用的评论，但我觉得它们没有提供任何附加值(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();
    }
}

我应该在 Controller 及其 Action 上使用什么风格的评论来提供附加值并增加评论的有用性？您已经使用了哪些评论？

Answer 1

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