3

私は 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();
    }
}

付加価値を提供し、コメントの有用性を高めるには、コントローラーとそのアクションでどのスタイルのコメントを使用する必要がありますか? すでに使用したコメントは何ですか?

4

4 に答える 4

10

コメントは、さまざまなメソッドの使用方法や、予想されるパラメーターと戻り値を説明するために他のユーザーが使用する予定の API に大きな価値をもたらします。あなた自身のコードでは、コントローラーとアクションの名前、およびそれらのパラメーターが自明であるか、少なくともコード自体から簡単に見つけられるようにすることをお勧めします。あなたのコードは、それが実際に何をするかについての最良のドキュメントです。コメントはほとんどの場合そうであるように、それ自体と同期がずれることはありません。コントローラー/アクションの場合、ほとんどの場合、フレームワーク自体が唯一のコンシューマーであるため、(まだ) 他の誰かが簡単に理解できるものにリファクタリングできていないコードについてはコメントを保存し、スキップすることをお勧めします。とにかく誰も読まないコメント。

于 2010-06-29T14:59:33.503 に答える
1

あなたのコードを見る開発者が asp.net MVC を知っているなら、彼らはあなたの簡単な例を理解するはずです。そのコードにコメントすると、asp.net MVC のチュートリアルを提供するだけで済みます。

于 2010-06-29T15:47:57.917 に答える
1

コントローラー メソッドで本当に役立つと思うのは、慣例から派生したものをコメントに入れることであり、コントローラー メソッドを見ても明らかではありません。

たとえば、次のように、コントローラー メソッドを呼び出す URL の形式を常に含めます。

// HTTP://mysite.com/mycontroller/myaction/id  <-- Customer ID

これにより、慣習によって隠されているすべてのものが一目でわかります。

要約コメントはもう少し具体的にする必要があります。

/// <summary>    
/// Displays a list of customers.    
/// </summary>
于 2010-06-29T15:06:08.840 に答える
0

それがMVCです。アーキテクチャはそれ自体で語っており、コメントはより困難な場合にのみ必要です。

この場合、アクション メソッドは HTML である ViewResult を返します。これは、セクションのコメントで指定するのに役立つ場合があります<returns>。

于 2010-06-29T14:58:52.783 に答える