Mike’s Dump

June 25, 2007

RE: Is there an issue with this or am I not getting enough oxygen?

Filed under: Code — mikesdump @ 2:01 pm

In my previous post I showed an example of what not to do when writing comments. To my amazement this non-rant generated almost as many comments as this post.

After reading the comments and giving it some more thought I wanted to post a follow-up. I don’t believe these type comments are unique to a tool like VBCommenter, one development shop or one programming language. I believe this is a very common issue when documenting source code.

I had another post a couple years ago about documentation and my views haven’t really changed. I still believe the most important piece of documentation for a project is the requirements.

If you insist in commenting the code (which I’m not arguing against) I suggest the following rules:

Document WHY not WHAT
Even really crappy code can be debugged. Call me sick but I kind of like debugging crappy code from time-to-time because it is extra satisfying when I fix it. When you are cursing the previous developer’s name are you screaming at them, “WHAT are you doing”? or “WHY did you do that”? I find it a lot easier to figure out the what but the why can be a little trickier.

Remember you who are writing for

The primary person the in code documentation is for is the developer(s) that inherit your code not for you. I believe a class header outlining the purpose of the class is far more valuable than commenting every method. If you had to explain the application to a developer that was going to take over for you what would you tell them? Would you say, “here is the page_load event, it will load the page”? Probably not, you are hopefully going to tell them some of the challenges you ran into and why the application is the way it is.

Never Copy and Paste Comment Block headers

Please, if you must copy comment headers remember to update them. I don’t know how many times over the years I have read the comments of method A right above method B because the developer copied the comments and didn’t update them.

Read them and keep them current

If you are maintaining some code and the person before you took the time to write good comments make sure they are still current after your change. If you aren’t going to bother updating them it is better to delete them than leave comments that don’t match the code.

Commenting code can add value to a project but it is a team effort. I don’t believe there is any magic to writing good comments but it does take time and you do have to put some thought into it. If you hate writing comments that much you could always try this.


June 20, 2007

Is there an issue with this or am I not getting enough oxygen?

Filed under: Code — mikesdump @ 1:43 pm
''' -----------------------------------------------------------------------------
''' <summary>
'''     Called on load of the page
''' </summary>
''' <param name="sender"></param>
''' <param name="e"></param>
''' <remarks>
''' </remarks>
''' <history>
''' 	Somebody	8/17/2005	Created
''' </history>
''' -----------------------------------------------------------------------------
Private Sub Page_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
End Sub

Ok. Instead of me going on a rant on why I think the above comment block is a complete waste of time and how it takes away from code readability instead of enhancing I’m hoping somebody, anybody can say something useful about a comment block like this.

(Some might argue that it tells you when the method was created but assume the development shop that produced this uses source control.)

Blog at WordPress.com.