Geeks With Blogs
Blog Moved to http://podwysocki.codebetter.com/ Blog Moved to http://podwysocki.codebetter.com/
Very recently on the CLI_DEV (formerly ALTNETCONF) mailing list, Joe Ocampo asked whether the standard saying, "Code Comments are an apology for bad design" holds in regards to documenting your non-public API.  I believe that question arose once before and usually a flame war erupts of some sort.

I found this button sums up my feelings best!



But, anyhow, it's a real valid question and believe it or not, people have quite strong opinions on the matter.  With tools like Resharper and other refactoring tools, it's quite easy for code comments to get out of sync, and therefore not really useful.  Your public and protected APIs should be pretty self describing. 

My usual feelings on the matter is this.  Use XML code comments in your public and protected APIs.  This includes not only declaring your parameters, but also your possible exceptions as well.  Without having something like Spec#, they can be the next best thing.  Something like this usually suffices for me.

/// <summary>
/// This adds the given value to the list, only if it is unique.
/// </summary>
/// <param name="value">The unique value to add to the collection</param>
/// <exception cref="System.ArgumentNullException"><paramref name="value"/> is <c>null</c></exception>
protected int AddValue(string value) { ... }

But, this is really only helpful on the public and protected stuff.  The inner workings usually get refactored too often for them to stay in sync and useful.

// TODOs are usually useful if you need reminders on where you need to put in more functionality before your code is complete.  I've found that is the case a few times, where it currently works, but look for refactoring opportunities.  // HACK: also works for me.

But, other than that, I like the noise to comments as low as possible, except if it isn't blatantly obvious what you are doing and why.  Maybe around 10% of code is commented suffices on non-public API code.  But, please don't tell me your opening a file, when I see it right before me.  Let the code do the talking.  Some legacy code just needs it because you can't refactor it as much for fear of breakage, so using it might not always be intuitive.  Yes, I know, straddling a fence...
kick it on DotNetKicks.com Posted on Wednesday, January 9, 2008 6:44 PM C# , Off-Topic | Back to top


Comments on this post: Are Code Comments An Apology for Bad Design?

No comments posted yet.
Your comment:
 (will show your gravatar)


Copyright © Matthew Podwysocki | Powered by: GeeksWithBlogs.net