评论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有很大的价值,以解释如何使用各种方法以及预期的参数和返回值.在您自己的代码中,我更喜欢控制器和操作的名称及其参数是不言自明的,或者至少可以从代码本身轻松发现.你的代码是它实际上做的最好的文档 - 它永远不会像评论那样与自己不同步.在控制器/操作的情况下,框架本身几乎总是唯一的消费者,所以我要说保存你的代码的评论,你还没有(还)能够重构成其他人容易理解的东西,并跳过无论如何都没有人会读到的评论.