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

XMLドキュメントは、パブリックAPIを使用する外部の関係者向けにドキュメント化する必要がある場合に最適です。私の意見では、コントローラーはそのカテゴリーに分類されません。

また、スリムなコントローラーに沿って、特にやなどの属性メタデータを使用して、それらが何をするかについて自明である必要が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 に答える