Mike’s Dump

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
Bla
Bla
Bla
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.)

Advertisements

8 Comments »

  1. This is just the result of a developer turning off his/her brain and dogmatically documenting everything, even if it includes private web events. At the risk of making myself look bad, I probably created this problem by forcing people to use tools like VBCommenter.

    While I like being able to generate documentation, it’s tough to figure out how to enforce the rules without turning everyone into robots. If there’s one thing that I’ve learned about 90% of .Net developers, they want somebody to tell them how to do the job rather than using their intelligence and creativity. Maybe I’m just jaded or maybe Edmonton is too overrun with NAIT grads that have a diploma/degree but really don’t know how to think.

    Geez…was that a rant? Don’t get me started on unit testing, coverage analysis, check-in comments, testing, refactoring…

    Comment by mike — June 21, 2007 @ 7:58 am | Reply

  2. P.S. Glad to see another article from you. You’ve got too many opinions – set them free! ๐Ÿ™‚

    Comment by mike — June 21, 2007 @ 8:00 am | Reply

  3. lol, agreed, these these things are worse than useless. I once worked at a company this one developer would religiously comment like so

    //page created
    procedure OnPageCreated …

    //save button clicked
    procedure btnSaveClick …

    //grdDisplay drawing items
    procedure grdDisplayDrawItem …

    and he was religious about it, we thought he had some kinda lame commenter, but he’d did it all manually. But he was a smart dude too. So we finally decided that he must’ve worked at a company where he got burned bad enough by some kinda "you must always document your code" that it became an ingraned self-preservation habit.

    I think the code block you highlighted would be great if someone were actually filling in the content, but I too have seen many such blank templates littering various codebases and they just get in the way and ocassionally distract you into thinking maybe there’s some reason for it. The worst part is that they decrease the signal to noise ratio too. As you begin to habitually ignore such useless comments, you miss the few that might actually contain useful information.

    Comment by jamesk — June 21, 2007 @ 9:37 am | Reply

  4. Now I know it’s my birthday! Mike Friesen posts *and* I get a chance to view a TMed McClenaghan rant! ๐Ÿ˜‰ Thanks guys, you shouldn’t have!

    Using my Columbo-like detective skills, I can figure out
    a) that this was likely created with VBCommenter
    b) that it was created in 2005!! (It’s that grasp of the startlingly obvious that keeps me in demand!)

    I don’t know that our team makeup back in 2005 (has it really been almost two years since then?) but I am laying odds that this was was likely done by someone who got a little zealous about how cool VBCommenter is and took it too far.

    For sure there is no replacement for critical thought. I think that might have been part of the cost of introducing so much to the team at that point in time, I think – there was so much to absorb people were just slavishly adhering to standard without understanding *why* we were adopting that sort of standard in the first place.

    It’s the same reason why unit testing/code coverage is a slow thing for some teams to adopt – they see the practice but don’t always understand why it’s important.

    Comment by Justice~! — June 22, 2007 @ 9:03 am | Reply

  5. @McClenaghan: "Maybe I’m just jaded or maybe Edmonton is too overrun with NAIT grads that have a diploma/degree but really don’t know how to think."

    This ties into that post I promised you a little while ago about teams, which actually *is* coming sometime this week! But more immediately:

    I spoke with a NAIT grad recently who informed me that when NAIT grads leave, they are prepped with an "info sheet" that will (and I’m quoting) "get them past a technical screen". Said sheet has a bunch of trivia questions about .NET that are supposedly common in the industry, as well as some jargon you should throw in if you want to make an impression.

    Interestingly enough, the following things are *not* talked about at NAIT, at least from this most recent grad’s perspective:

    * NUnit based unit testing and why it’s important
    * Proper architecture
    * Domain driven design and development
    * Code coverage tools and what they mean
    * How to critically refactor

    I know it’s a bit of a tangent, but the culture at NAIT often *produces* people who are blindly following things without questioning, and just "doing their jobs" without ever trying to push themselves to get better. Hell, when your school is giving you an *interview cheat sheet*, doesn’t that probably point out that the diploma program isn’t even teaching you the basics of what you need to know?

    Grrr. I think I have another post coming out of this. I hate the fact that NAIT sets up so many people to fail just out of school. That being said, you can’t go to school to learn how to be an independent thinker; that’s something you have to learn on your own.

    Comment by Justice~! — June 22, 2007 @ 9:14 am | Reply

  6. RE – "Maybe I’m just jaded or maybe Edmonton is too overrun with NAIT grads that have a diploma/degree but really don’t know how to think."

    That is the most fucking ignorant/retarded thing I have ever heard… Seriously…

    Comment by Jonas Avellana — June 27, 2007 @ 12:43 pm | Reply

  7. It’s VBCommenter. I can admit that I used everywhere because it was pushed down onto me and I didn’t know better. Now I do. Developers get better with time.

    This is a alright article on commenting that I came across.
    http://www.ibm.com/developerworks/linux/library/l-clear-code/?ca=dgr-FClnxw01linuxcodetips

    This reminds me of Arrested Development…

    Gob: Yeah, the guy wearing the $4,000 suit is holding the elevator for the guy who doesn’t make that in four months. Come on.
    [in the bathroom]

    Comment by James W — June 27, 2007 @ 12:50 pm | Reply

  8. […] 25th, 2007 at 2:01 pm (Code) In my previous post I showed an example of what not to do when writing comments. To my amazement this non-rant […]

    Pingback by RE: Is there an issue with this or am I not getting enough oxygen? « Mike’s Dump — September 8, 2007 @ 8:32 pm | Reply


RSS feed for comments on this post. TrackBack URI

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

Create a free website or blog at WordPress.com.

%d bloggers like this: