Geeks With Blogs
Eron Wright - All Killer No Filler blog

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.

Posted on Thursday, May 27, 2004 6:46 AM Technology | Back to top


Comments on this post: Use C# comment styles to your advantage

# re: Use C# comment styles to your advantage
Requesting Gravatar...
good idea
Left by Brad on Nov 19, 2004 1:05 PM

# re: Use C# comment styles to your advantage
Requesting Gravatar...
Left by bsknuisss on Dec 11, 2007 2:41 AM

# re: Use C# comment styles to your advantage
Requesting Gravatar...
I like /* */-style
Left by intranet on Jan 06, 2008 6:27 AM

# re: Use C# comment styles to your advantage
Requesting Gravatar...
I like you ideas and enjoy your news letter but frankly i find you to be an asshole. Last night at dinner when you got mad at my wife and hit her in the teeth was completely unnacceptable. All she said was she didnt like your tie. I mean jesus christ. It was a big deal! At least she is used to getting bopped everyonce in a while! See at christmas brosef
Left by tosha on Jun 03, 2009 11:32 PM

# re: Use C# comment styles to your advantage
Requesting Gravatar...
Left by wow on Aug 17, 2009 9:30 PM

# re: Use C# comment styles to your advantage
Requesting Gravatar...

Nice article, very helpful.
Thanks!!

nike air
Left by klecike on Sep 07, 2009 8:18 AM

# re: 3M Half Marathon
Requesting Gravatar...
That Post is Full of informative. Thanks for that kind of sharing. Hope u will again share with us.
Left by discount gucci handbags on Mar 14, 2011 10:49 PM

# re: Use C# comment styles to your advantage
Requesting Gravatar...
I have found it really useful.
Left by truereligionwest on Mar 31, 2011 1:48 AM

# re: Use C# comment styles to your advantage
Requesting Gravatar...
thanks for the news
karen millen dresses
Left by karen millen dresses on Apr 23, 2011 4:43 AM

# re: Use C# comment styles to your advantage
Requesting Gravatar...
Thanks for sharing this great piece of information. Do keep us update with some more updates. I love your blog very much. Finding something like this is very rare!
Left by female hair loss on May 11, 2011 4:34 AM

# re: Use C# comment styles to your advantage
Requesting Gravatar...
Thanks for posting this,.
Left by Rockwool Insulation on Jun 28, 2011 8:48 AM

# re: Use C# comment styles to your advantage
Requesting Gravatar...
Thanks for posting this,. its really nice post thanks again
Left by Rockwool Insulation on Jun 28, 2011 8:49 AM

# re: Use C# comment styles to your advantage
Requesting Gravatar...
I recently tried to use your flash app, the package throws an exception on installation under Umbraco 4. The files are imported, but when I get to step 5 there is no Gallery Example node.

I have read a few of the articles on your website now, and I really like your style of blogging
Left by gucci outlet online on Jul 08, 2011 8:26 PM

# Nice share.
Requesting Gravatar...
Researching new phosphor materials (which are currently being used in fluorescent lighting as well) that make LED light “warmer”[url=http://www.sino-buy.com/index.php?route=product/product&path=68&product_id=409]Outdoor LED Flood Lights[/url]
Left by Outdoor LED Flood Lights on Jul 16, 2011 12:40 AM

Your comment:
 (will show your gravatar)


Copyright © Eron Wright | Powered by: GeeksWithBlogs.net