3

我非常喜欢.NET中的 XML 文档。

但是，老实说，我从来没有见过一个教程或项目，例如，我们有这样的标记：

/// <summary>
/// dummy text
/// </summary>
/// <returns>blah</returns>
public ActionResult LogOff() {
    FormsService.SignOut();

    return RedirectToAction("Index", "Home");
}

代替：

// **************************************
// URL: /Account/LogOff
// **************************************

public ActionResult LogOff() {
    FormsService.SignOut();

    return RedirectToAction("Index", "Home");
}

这有什么特别的原因吗？我是唯一一个想要记录我的控制器方法的人吗？

编辑1：

虽然大多数控制器方法似乎很简单，但在说这个问题中详细说明的情况如何：MVC：如何使用具有许多子实体的实体？?

4

2 回答 2

8

当需要为使用它的外部各方记录公共 API 时，XML 文档非常有用。在我看来，控制器不属于这一类。

同样与苗条控制器一致，它们应该对它们的作用进行自我解释，尤其是对于属性元数据，例如HttpPost和HttpGet。

您是否设想第三方将您的控制器用作 API？

于 2011-02-25T00:23:36.293 回答
2

我通常会记录我的控制器操作，并简要说明该操作的用途，例如：

/// <summary>
/// Controller for viewing and updating the jobs list.
/// </summary>
public class JobsController : Controller
{
    /// <summary>
    /// Displays a list of all jobs for a given site.
    /// </summary>
    /// <param name="siteId">Id of the site to view jobs for.</param>
    public ActionResult Index(string siteId);

    /// <summary>
    /// Displays a detail view of a single job.
    /// </summary>
    /// <param name="id">Id of the job to view.</param> 
    public ActionResult Detail(string id);
}

它与我的其他类的 xml 文档不太一样，因为这些类永远不会被直接使用，因此它对站点/页面行为的文档比其他任何东西都多。也就是说，我发现描述操作的作用和参数是什么很有用，这里是一个很好的地方。

请注意，我没有包含路径 - 不仅因为如果路径更改信息已过时，还因为通过查看路由映射应该很明显路径将是什么。

更新/回复评论：

此类文档可能看起来完全没有意义，因为无论如何这些类几乎都是自我描述的，但是在适当结构化的代码中命名良好的方法上，这通常是 XML 文档的情况。但是，我仍然相信这种文档会增加价值：

  • 它用简单的英语阐明了类/方法/参数的作用
  • In 确认没有发生什么特别的事情（与某人只是不费心编写文档相反）。

请注意，我没有记录返回值，因为我对此绝对没有任何用处。

您还需要考虑到这个示例非常人为 - 可能某些参数是 JSON 序列化数据，或者负值意味着完全不同的东西。我对 XML 文档的看法是，要么不记录任何内容，要么记录所有内容（无论多么明显）。如果只记录了一半的方法，那么您永远无法判断它是因为它完全显而易见，还是开发人员只是太懒了——还要考虑到方法的目的对其他人来说可能不像对您那样明显。

例如，我不费心为事件处理程序编写文档（我曾经这样做过，但评论总是完全相同）。

于 2011-02-25T04:00:07.783 回答