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);
   9:         //  Establish the MDI child releationship
  10:         _PluginGalleryBrowserForm.MdiParent = this;
  12:         // Set window state to normal
  13:         _PluginGalleryBrowserForm.WindowState = FormWindowState.Normal;
  14:     }
  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.  

Comments (1)
  1. Colby Africa says:

    I am working hard today to get mpFx ready for Code Gallery.  I might make it. I have work time scheduled

Comments are closed.

Skip to main content