Comments within a C# method body tend to A) make a problem statement then B) document the steps to solve the problem. The problem statements tend to be multi-line; the details of the solution tend to be single-line.
I want the problem statements to stand out. Traditionally I use #region blocks to group the problems. Unfortunately, regions are single-line. They are also slightly more laborous to construct.
Lately I have been using a triple-slash comment block at the top of the method body to state the problem:
/// <summary>
/// Occurs when the page loads.
/// </summary>
private void Page_Load(object sender, System.EventArgs e)
{
/// Configure the http response to return a correct set of
/// cache headers. Validation headers must also be returned.
// set the etag
this.Response.Cache.SetETag("055aba934a3c21:380");
// set the cache policy
this.Response.Cache.SetCacheability(HttpCacheability.Public);
}
Another reason to use the triple-slash comment block within a method body, as opposed to the <remarks> block, is that it does not form a part of the API documentation. That is, the client-supplier relationship plays a role here. It is desirable to separate interface documentation from implementation documentation - they are intended for two different audiences. For a given method the external documentation should be placed in a <remarks> block above the method declaration; the internal documentation should be placed in triple-comment blocks at the top of the method body. It will naturally stand out from the implementation specifics.
This approach works better than using /* */-style comments blocks because such comments cannot be nested.
Incidentally, VS.NET has a handy button on the Text Editor toolbar to comment out the selected lines. It adds double-slash comments at the extreme left side. A complementary button exists that will uncomment the selected lines. It seems that left-justified comments are reserved for commenting-out code, not documentation.