“Who could hate comments so much that they would label them as a code smell?” I thought.

Well, I had an epiphany the other day.

I’ve never seen a block of code that actually needed a comment. Ever.

If you have a section of code that feels too complex, instead of adding a comment do any/all of the following and you can, in almost every case, reduce the need for comments by 100%:

1. add a sourcecontrol commit comment
2. do a simple refactor (Compose Method ftw people),
3. use more descriptive variable/function/class/whatever names.

If you do all of these things and the code you are working on still seems too complex, you may have bigger problems with your overall architecture/design and adding a comment isn’t going to help. In this case it’s time to go back to the drawing board.

Also, everytime you commit a changeset into sourcecontrol that contains a section of code commented out god kills a kitten. Please think of the kittens.

And then you get an email one day:

“Everything is broken. We’ve kidnapped your dog. Fix our site or you’ll never see Spartacus again.”

And before you have time to wonder why you ever named your dog “Spartacus” to begin with (i mean come. on.), you’re off in debug hell. You load the site and see all sorts of weird errors:

“$().ready is not a function”

“$(document) doesn’t support this property or method”

Or my personal favorite:

“null is null or not an object”

You open up FireFox, activate FireBug, load the console, and type “alert($)”, press run, and instead of seeing the expected jQuery function:

function (E, F) {
    return new (o.fn.init)(E, F);
}

You instead get:

function $(element) {
    if (arguments.length > 1) {
        for (var i = 0, elements = [], length = arguments.length; i < length; i++) {
            elements.push($(arguments[i]));
        }
        return elements;
    }
    if (Object.isString(element)) {
        element = document.getElementById(element);
    }
    return Element.extend(element);
}

Or even:

function $(id) {
    return document.getElementById(id);
}

DOH! Looks like another javascript library has been loaded and has overwritten the $() shortcut for jQuery. Woe is I. Why can’t we all just get along?!?

Well, we can’t stop people from including their favorite javascript libraries, but what we can do is prevent our code from suffering as a result. We’ll need a nice, big beefy, bodyguard to make sure our code isn’t messed with while it’s out clubbing with Prototype, Scriptaculous or even MooTools (who invited him??!?).

Here’s what our bodyguard function will look like

( function($) {

} ) ( jQuery );

So what this does is call our anonymous function and pass the jQuery object. This will scope ‘$’ to within our little function so we won’t step on anyone else’s toes (and they won’t bump into us while we’re on the dance floor and spill our drink everywhere). Okay, I think I've taken the clubbing metaphor far enough.

Basically this will allow our code to run and use the $ shortcut for JQuery as if it were loaded without any of these other libraries on the page.

Here is what the completed code would look like:

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.1/jquery.min.js" type="text/javascript">
</script>

<script src="http://ajax.googleapis.com/ajax/libs/prototype/1.6.1.0/prototype.js" type="text/javascript">
</script>
<script src="http://ajax.googleapis.com/ajax/libs/scriptaculous/1.8.3/scriptaculous.js" type="text/javascript">
</script>

<script type="text/javascript">
( function($) {
    // we can now rely on $ within the safety of our “bodyguard” function
    $(document).ready( function() { alert("nyah nyah! I’m able to use '$'!!!!");  } );
} ) ( jQuery );

//this will fail
$(document).ready( function() { alert('fail?'); } );
</script>

I love using this simple self-calling anonymous function style when working with jQuery because it saves me from typing jQuery(), which really does look a lot more ugly than using the $() shortcut. It also protects my code from any scoping issues and lets the code function normally when jQuery is put into no conflict mode.

My opinion, if you're doing work in jQuery on sites that you don't control 100%, you should be using this method to protect your code and your clients.

Updated: changed link for jquery to use 1.4.1 at the google CDN (tsk, tsk, tsk I was using the googlecode.com link)

It used IL replacement, much like TypeMock Isolator, to allow developers to enable/disable the logger without having to compile any code.

In theory, I haven’t tried it out yet, you would be able to add this logging system to any project without coding anything.

I downloaded the code and it’s huge. 5 assemblies, over 2000 lines and there is some COM stuff in there. I notice two things. First it’s all in c++. This is not a bad thing it’s just not my first language.

So I start looking around for some comments to let me know what the heck is going on in this code.

Annnnnnd… hmmmm thats odd.

There are no comments. Not one. I checked the author notes on the original submission article to see if this was an error and there was an updated link.

Nope. Nothing. It takes me a minute but near the bottom of the post I see why there are no comments.

The author writes:

“I like to think I write self-documenting code so I tend to not have any comments in my code.”

I instantly deleted the code from my system. My thought is if the author of this code didn’t think it was worthy of some kind of explanation then I am certainly not going to waste my time with it.

Comments aren’t just some “nice to have” thing. They show that you actually care about what you are putting out there and they show your thought process throughout the codes execution. If you don’t care about that then why would I?

I’m not saying that every line, function call and variable needs a comment but any programmer worth his salt should put some form of documentation into his/her code. It’s a sign of respect.

So my fellow developers let’s respect each other enough to document what we put out into the world. What do you say?