Wise man or Wise guy? You Decide

Just another WordPress.com weblog

How’s your commentary?

Posted by sqlwiseguy on January 7, 2009

Steve Jones had a good editorial on SQLServerCentral, A Dearth of Comments, this past Monday. One way I measure a good editorial is the discussion it generates and this one generated an interesting one.

There are generally 2 camps for commenting code:

  1. My code is self-documenting.
  2. People in this camp usually have more verbose method, property, and variable names.

  3. I want the next person to know what I was doing and why. Oh, and I want to be able to remember when I go back in 6 months.
  4. People in this camp sometimes over comment. This folks will take a Insert Into table Select From tableB and put this comment at the top “this inserts a row into tableA from tableB”.

I have to admit that in practice I am more in the first camp, although I’d like to move toward, but not all the way into the second camp. When I was learning to program, my boss\mentor was and, to the best of my knowledge, is firmly entrenched in the first camp. The fact that I have had to spend some time debugging and upgrading his code certainly is playing a part in my desire to do more commenting. Here are a couple of things I picked up from the SSC discussion that I am going to try to implement as I move forward:

  1. Comment why I am doing what I am doing and why I am doing it this particular way. Any good developer should be able to figure out what the code does, but not necessarily the why. Thanks Roger Plowman and those who seconded his comment.
  2. Comment so a novice, either in programming or business knowledge, can understand what the code does and why. Several people mentioned it in the thread.
  3. Create the why and how comments BEFORE beginning. Really this is putting together a plan, and will probably be the hardest one for me as I like to “dive” right in. Thanks Jay Holovacs and others who mentioned this.
  4. Push for and get an intranet Wiki or Knowledge Base. My first job had one and it was great. Where I’m at now does not, which means the developer who wrote it, supports it. Not that I don’t want to support my code, but I don’t need to be the only one who can do it. Thanks again to Roger Plowman and others.

I’ve always done a good job with a header on stored procedures and triggers (see this post), but not within the code or in my VB or C# code.

So now you know that my “commentary” is mediocre at best, but how’s yours?

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

 
%d bloggers like this: