Comments (in Code)

I love comments when they are appropriate and necessary.  I relish a good comment in a piece of code that does something really beautiful but is maybe complicated.  I love comments that help me understand the assumptions and design considerations that underpin a piece of code. 

However...The best documentation is well written code.  Code that is overly commented is actually harder to read then clean code.  Code that employs the “one comment for every line” paradigm makes me want to shove pencils in my eyeballs and call it good.

Here is an example (I took a piece of code of mine and added the comments to emulate this comment-per-line nonsense):

    1: private void ShowPluginGalleryBrowser()

    2: {

    3:     // If the plugin field is null or disposed, we need to create a new instance

    4:     if (_PluginGalleryBrowserForm == null || _PluginGalleryBrowserForm.IsDisposed)

    5:     {

    6:         //  Create a new instance and hand the form the PluginHost object

    7:         _PluginGalleryBrowserForm = new PluginGalleryBrowserForm(_PluginHost);

    8:  

    9:         //  Establish the MDI child releationship

   10:         _PluginGalleryBrowserForm.MdiParent = this;

   11:  

   12:         // Set window state to normal

   13:         _PluginGalleryBrowserForm.WindowState = FormWindowState.Normal;

   14:     }

   15:  

   16:     // Show the plugin gallery browser

   17:     _PluginGalleryBrowserForm.Show();

   18: }

Okay, let’s look at each line of comment code:

3.)   Let’s see, the C# if statement is really complicated so I better explain that I am checking to see if a field is null or if it is disposed of

7.)   Boy, let’s hope the reader understands how the C# new keyword works and that I can have a constructor that takes an object, but just in case they don’t, let me explain it in a comment

10.)  While .MdiParent = this is pretty clear, I better explain that I am making this new plugin gallery browser form a MDI child of this form

Etc, etc.  You get the point.

This is insane.