注释 ASP.NET MVC 控制器
我是 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();
}
}
我应该在控制器及其操作上使用什么类型的注释来提供附加值并增加注释的有用性？您已经使用过哪些评论？
I am a big fan of Stylecop and I always follow it guidelines. I also follow the guideline that state that a comment should bring added value to the code and not repeat what the code is doing.
I'm having a bit of trouble following the commenting guidelines concerning an ASP.NET MVC Controller and its related actions: I can't think about the comments to go on an action, nor the controller.
Let's assume the default HomeController and the default Index action, this is the comments I'm using, but I don't feel like they provide any added 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();
}
}
What style of comments should I use on a controller and its actions that would provide added value and increase the usefulness of a comment? What comments have you already used?
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（4）
如果查看您代码的开发人员了解 asp.net MVC，他们应该理解您的简单示例。如果您评论该代码，您所做的就是提供 ASP.NET MVC 教程
If a developer who looks at your code knows asp.net MVC they should understand your simple example. If you comment that code all you'll be doing is giving a tutorial of asp.net MVC
注释对于其他人将使用的 API 具有很大的价值，可以解释如何使用各种方法以及预期的参数和返回值是什么。在您自己的代码中，我希望控制器和操作的名称以及它们的参数是不言自明的，或者至少可以从代码本身轻松发现。您的代码是其实际用途的最佳文档——它永远不会像注释几乎总是那样与自身不同步。在控制器/操作的情况下，框架本身几乎总是唯一的消费者，所以我想说，保存您对那些您还没有能够重构为其他人容易理解的内容的代码的评论，并跳过无论如何，没有人会读到的评论。
Comments have great value on APIs that others are going to consume to explain how to use the various methods and what the expected parameters and return values are. In your own code, I'd prefer that the names of controllers and actions as well as their parameters be self-explanatory or, at least, easily discovered from the code itself. Your code is the best documentation for what it actually does -- it never gets out of sync with itself as comments nearly always do. In the case of controllers/actions the framework itself is almost always the only consumer, so I'd say to save your comments for code that you haven't (yet) been able to refactor into something easily understandable by someone else and skip the comments that no one will ever read anyway.
这就是 MVC。该架构不言自明，只有在更困难的情况下才需要注释。
在本例中，action 方法返回一个 ViewResult，它是 HTML。这可能有助于在
That's MVC. The architecture talks for itself, and comments are needed only in more difficult cases.
In this case, the action method returns a ViewResult, which is HTML. This might help specify in the comments for the
<returns>section.我发现对控制器方法真正有用的是将这些内容放在源自约定的注释中，并且从查看控制器方法来看并不明显。
例如，我总是包含调用控制器方法的 URL 形式，如下所示：
这会一目了然地告诉您按惯例隐藏的所有内容。
摘要评论应该更具体一些：
What I find really useful for controller methods is to put those things in the comments that derive from convention, and are not obvious from looking at the controller method.
For example, I always include a form of the URL that calls the controller method, like this:
This tells you at a glance all of the stuff hidden by convention.
The summary comment should be a bit more specific: