Photo of source code from this site

Writing Better JavaScript Through Comments

Posted on:
February 9, 2015
Posted in:
JavaScript, Web Dev

When you want to write code that’s easy to understand and update, it can be tough to know where to start. This article outlines a technique for writing clear code for your site.

For the purposes of this article, let’s consider the actual YouTube code I’m using on my website. This code requires jQuery, but hopefully it’ll be so clear that you’ll still be able to read it even if jQuery is new to you.

State Your Intent

Your first step is to write an opening comment block explaining what the code does. Once you write the comment, write the object prototype, then fill it in with pseudo code explaining what it should do.

/**
object mpYouTubeVideo
    arguments        inObj        DOM Node for YouTube IFRAME
    description        Makes a javascript object tied to a DOM node
                    that resizes the video to fit its parent container
                    (100% width, 16:9 aspect ratio)
**/

function mpYouTubeVideo (inObj) {
	// save a copy of the object

	// register resizeHandler & call
}

Part of our pseudo code here says that we need to register an event handler – so we’ll use the same process to add an event handler function to our object.

First we’ll create the comment describing the function, then the prototype, and then outline what the function does using pseudo code.

/**
object mpYouTubeVideo
    arguments        inObj        DOM Node for YouTube IFRAME
    description        Makes a javascript object tied to a DOM node
                    that resizes the video to fit its parent container
                    (100% width, 16:9 aspect ratio)
**/
function mpYouTubeVideo (inObj) {
	// save a copy of the object

	/**
	function resizeHandler
		arguments			e 			jQuery event
		returns				nothing
		description			Adjusts video size as responsive site moves around
	**/
	this.resizeHandler = function (e) {
		// get the parent width

		// calculate video height assuming 16x9

		// set video's width & height
	}

	// register resizeHandler & call
}

Fill It All In

Now that we’ve got a clear description of what our object does, we can start writing the source code that makes all that stuff happen. As long as you’ve written out some sound pseudo code, you won’t have to worry about backtracking or spaghetti code. Just write the code that does what the comment says.

/**
object mpYouTubeVideo
    arguments        inObj        DOM Node for YouTube IFRAME
    description        Makes a javascript object tied to a DOM node
                    that resizes the video to fit its parent container
                    (100% width, 16:9 aspect ratio)
**/
function mpYouTubeVideo (inObj) {
	// save a copy of the object
	this.obj = inObj;

	/**
	function resizeHandler
		arguments			e 			jQuery event
		returns				nothing
		description			Adjusts video size as responsive site moves around
	**/
	this.resizeHandler = function (e) {
		// get the parent width
		var parentWidth = $(this.obj.parentNode).innerWidth();

		// calculate video height assuming 16x9
		var vidHeight = parentWidth*9/16;

		// set video's width & height
		$(this.obj).css("width", parentWidth+"px");
		$(this.obj).css("height", vidHeight+"px");
	}

	// register resizeHandler & call
	$(window).resize(this.resizeHandler.bind(this));
	this.resizeHandler(null);
}

If you need to go back and add things later, make sure you flesh them out in pseudo code first and then tackle the code later.

Clarity vs. Speed

This method for writing code doesn’t actually give you too many problems when it comes to speedy code. The interpreter will ignore your comments, and if you minify your scripts you won’t have to worry about visitors having to download them since they’ll be stripped out.

(I don’t minify code on this site, BTW, because I want visitors to be able to read it.)

Demonstration

Here’s that code in action.